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
```