0
# setproctitle
1

2
A cross-platform Python module that allows processes to customize their title as displayed by system monitoring tools like `ps`, `top`, and Activity Monitor. The module wraps around PostgreSQL's multi-platform implementation and includes both a C extension for optimal performance and pure Python fallback functions.
3

4
## Package Information
5

6
- **Package Name**: setproctitle
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install setproctitle`
10

11
## Core Imports
12

13
```python
14
import setproctitle
15
```
16

17
For importing specific functions:
18

19
```python
20
from setproctitle import setproctitle, getproctitle, setthreadtitle, getthreadtitle
21
```
22

23
## Basic Usage
24

25
```python
26
import setproctitle
27

28
# Set the process title
29
setproctitle.setproctitle("my-worker-process")
30

31
# Get the current process title
32
current_title = setproctitle.getproctitle()
33
print(f"Current process title: {current_title}")
34

35
# Set thread title (on supported platforms)
36
setproctitle.setthreadtitle("worker-thread-1")
37

38
# Get current thread title
39
thread_title = setproctitle.getthreadtitle()
40
print(f"Current thread title: {thread_title}")
41
```
42

43
## Architecture
44

45
The module provides a dual-implementation architecture:
46

47
- **C Extension (`_setproctitle`)**: High-performance native implementation for optimal performance
48
- **Python Fallback**: Pure Python implementations that provide basic functionality when C extension is unavailable
49
- **Platform Support**: Optimized implementations for GNU/Linux, BSD, macOS, and Windows with platform-specific behaviors
50
- **Environment Configuration**: Behavior customization through environment variables
51

52
## Capabilities
53

54
### Process Title Management
55

56
Functions for setting and retrieving the current process title as displayed by system monitoring tools.
57

58
```python { .api }
59
def setproctitle(title: str) -> None:
60
    """
61
    Set title as the title for the current process.
62
    
63
    Parameters:
64
    - title (str): The new process title to set
65
    
66
    Returns:
67
    None
68
    
69
    Notes:
70
    The process title is visible in /proc/PID/cmdline, /proc/PID/status, 
71
    /proc/PID/comm files and used by tools like ps and top.
72
    """
73

74
def getproctitle() -> str:
75
    """
76
    Return the current process title.
77
    
78
    Parameters:
79
    None
80
    
81
    Returns:
82
    str: Current process title, or command line arguments joined by spaces
83
         if C extension unavailable
84
    """
85
```
86

87
### Thread Title Management
88

89
Functions for setting and retrieving the current thread title on supported platforms.
90

91
```python { .api }
92
def setthreadtitle(title: str) -> None:
93
    """
94
    Set title as the title for the current thread.
95
    
96
    Parameters:
97
    - title (str): The new thread title to set
98
    
99
    Returns:
100
    None
101
    
102
    Notes:
103
    Thread title is exposed as /proc/PID/task/TID/comm on supported platforms
104
    and used by tools like htop.
105
    """
106

107
def getthreadtitle() -> str:
108
    """
109
    Get the current thread title.
110
    
111
    Parameters:
112
    None
113
    
114
    Returns:
115
    str: Current thread title, or empty string if C extension unavailable
116
    """
117
```
118

119
## Environment Variables
120

121
The module behavior can be customized using environment variables:
122

123
- **SPT_NOENV**: Set to any non-empty value to avoid clobbering `/proc/PID/environ`. This limits the maximum title length to the command line length but preserves the environ file.
124

125
- **SPT_DEBUG**: Set to any non-empty value to print debug information on stderr. Most useful information is printed during module import.
126

127
## Platform-Specific Behavior
128

129
### Linux
130
- Uses `sys/prctl.h` for process title manipulation
131
- Full support for both process and thread titles
132

133
### BSD
134
- Uses native `setproctitle()` system call
135
- Built-in platform support with `HAVE_SETPROCTITLE` and `HAVE_PS_STRING` definitions
136

137
### macOS
138
- Includes `darwin_set_process_name.c` for platform-specific implementation
139
- Automatic initialization via `getproctitle()` call to avoid fork() issues
140
- Defined with `__darwin__` symbol
141

142
### Windows
143
- Creates Named Objects readable by Process Explorer
144
- No actual process title change capability
145
- Process title changes are visible through specialized monitoring tools
146

147
## Error Handling
148

149
The module provides graceful degradation:
150

151
- When C extension fails to load, pure Python fallbacks are automatically used
152
- Debug logging is available via `SPT_DEBUG` environment variable
153
- Import errors are logged but don't prevent module usage
154
- Platform-specific initialization is handled automatically
155

156
## Usage Examples
157

158
### Multi-process Application
159

160
```python
161
import os
162
import setproctitle
163
from multiprocessing import Process
164

165
def worker_process(worker_id):
166
    # Set descriptive process title for this worker
167
    setproctitle.setproctitle(f"myapp-worker-{worker_id}")
168
    
169
    # Do work...
170
    print(f"Worker {worker_id} running with title: {setproctitle.getproctitle()}")
171

172
if __name__ == "__main__":
173
    # Set main process title
174
    setproctitle.setproctitle("myapp-master")
175
    
176
    # Start worker processes
177
    processes = []
178
    for i in range(3):
179
        p = Process(target=worker_process, args=(i,))
180
        p.start()
181
        processes.append(p)
182
    
183
    # Wait for all workers
184
    for p in processes:
185
        p.join()
186
```
187

188
### Thread Title Management
189

190
```python
191
import threading
192
import setproctitle
193

194
def worker_thread(thread_name):
195
    # Set thread title for monitoring
196
    setproctitle.setthreadtitle(f"worker-{thread_name}")
197
    
198
    # Do thread work...
199
    print(f"Thread {thread_name} title: {setproctitle.getthreadtitle()}")
200

201
# Create and start threads
202
threads = []
203
for i in range(3):
204
    t = threading.Thread(target=worker_thread, args=(f"thread-{i}",))
205
    t.start()
206
    threads.append(t)
207

208
# Wait for completion
209
for t in threads:
210
    t.join()
211
```