processtitle 1.3__cp315-cp315-win_arm64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- processtitle/__init__.py +18 -0
- processtitle/__main__.py +123 -0
- processtitle/_processtitle.cp315-win_arm64.pyd +0 -0
- processtitle/_processtitle.pyi +46 -0
- processtitle/py.typed +0 -0
- processtitle-1.3.dist-info/METADATA +271 -0
- processtitle-1.3.dist-info/RECORD +12 -0
- processtitle-1.3.dist-info/WHEEL +5 -0
- processtitle-1.3.dist-info/entry_points.txt +2 -0
- processtitle-1.3.dist-info/licenses/Acknowledgments.md +101 -0
- processtitle-1.3.dist-info/licenses/LICENSE +29 -0
- processtitle-1.3.dist-info/top_level.txt +1 -0
processtitle/__init__.py
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
# Copyright (c) 2026, Eugene Gershnik
|
|
2
|
+
# SPDX-License-Identifier: BSD-3-Clause
|
|
3
|
+
|
|
4
|
+
"""processtitle package"""
|
|
5
|
+
|
|
6
|
+
__version__ = '1.3'
|
|
7
|
+
|
|
8
|
+
from ._processtitle import (
|
|
9
|
+
prepare,
|
|
10
|
+
set_to,
|
|
11
|
+
last_set
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
__all__ = [
|
|
15
|
+
'prepare',
|
|
16
|
+
'set_to',
|
|
17
|
+
'last_set'
|
|
18
|
+
]
|
processtitle/__main__.py
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# Copyright (c) 2026, Eugene Gershnik
|
|
2
|
+
# SPDX-License-Identifier: BSD-3-Clause
|
|
3
|
+
|
|
4
|
+
"""Command line utility to list process titles"""
|
|
5
|
+
|
|
6
|
+
import sys
|
|
7
|
+
import os
|
|
8
|
+
import argparse
|
|
9
|
+
import subprocess
|
|
10
|
+
import shutil
|
|
11
|
+
import re
|
|
12
|
+
import textwrap
|
|
13
|
+
import locale
|
|
14
|
+
|
|
15
|
+
from pathlib import Path
|
|
16
|
+
|
|
17
|
+
from . import __version__
|
|
18
|
+
|
|
19
|
+
def _do_busybox(args, ps: Path):
|
|
20
|
+
cmd = [ps, '-opid,args']
|
|
21
|
+
if args.pids is None:
|
|
22
|
+
proc = subprocess.run(cmd, check=False)
|
|
23
|
+
return proc.returncode
|
|
24
|
+
|
|
25
|
+
encoding = locale.getpreferredencoding(do_setlocale=False)
|
|
26
|
+
proc = subprocess.Popen(cmd, encoding=encoding, stdout=subprocess.PIPE)
|
|
27
|
+
assert proc.stdout is not None
|
|
28
|
+
expr = re.compile(r'^\s*([0-9]+) ')
|
|
29
|
+
for line in proc.stdout:
|
|
30
|
+
if (m := expr.search(line)):
|
|
31
|
+
pid = int(m.group(1))
|
|
32
|
+
if pid in args.pids:
|
|
33
|
+
print(line, end='')
|
|
34
|
+
else:
|
|
35
|
+
print(line, end='')
|
|
36
|
+
retcode = proc.wait()
|
|
37
|
+
return retcode
|
|
38
|
+
|
|
39
|
+
def _do_unix(args):
|
|
40
|
+
path = os.environ.get('PATH', '/bin:/usr/bin')
|
|
41
|
+
ps = shutil.which('ps', path=path)
|
|
42
|
+
if ps is None:
|
|
43
|
+
print('ps utility not found', file=sys.stderr, flush=True)
|
|
44
|
+
return 1
|
|
45
|
+
|
|
46
|
+
test = Path(ps)
|
|
47
|
+
if test.is_symlink():
|
|
48
|
+
dest = test.readlink()
|
|
49
|
+
if dest.name == 'busybox':
|
|
50
|
+
return _do_busybox(args, Path(ps))
|
|
51
|
+
|
|
52
|
+
cmd = [ps]
|
|
53
|
+
|
|
54
|
+
if sys.platform.startswith("sunos"):
|
|
55
|
+
cmd += ['-F', '-opid,args']
|
|
56
|
+
else:
|
|
57
|
+
cmd += ['-opid,command']
|
|
58
|
+
|
|
59
|
+
if args.pids is not None:
|
|
60
|
+
if sys.platform == "linux":
|
|
61
|
+
cmd += ['-q', ','.join([str(pid) for pid in args.pids])]
|
|
62
|
+
else:
|
|
63
|
+
cmd += ['-p', ','.join([str(pid) for pid in args.pids])]
|
|
64
|
+
elif args.show_all:
|
|
65
|
+
cmd += ['-A']
|
|
66
|
+
|
|
67
|
+
proc = subprocess.run(cmd, check=False)
|
|
68
|
+
return proc.returncode
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _do_win(args):
|
|
72
|
+
powershell = shutil.which('powershell')
|
|
73
|
+
if powershell is None:
|
|
74
|
+
print('powershell not found', file=sys.stderr, flush=True)
|
|
75
|
+
return 1
|
|
76
|
+
|
|
77
|
+
pids = ''
|
|
78
|
+
filter = ''
|
|
79
|
+
if not args.show_all:
|
|
80
|
+
filter += '| Where-Object { $sessionId -eq $_.SessionId } '
|
|
81
|
+
if args.pids is not None:
|
|
82
|
+
pids = ', '.join(str(pid) for pid in args.pids)
|
|
83
|
+
filter += '| Where-Object { $pids -contains $_.ProcessId } '
|
|
84
|
+
input = textwrap.dedent('''
|
|
85
|
+
$ErrorActionPreference = 'Stop'
|
|
86
|
+
$pids = @( ''' + pids + ''' )
|
|
87
|
+
$sessionId = [System.Diagnostics.Process]::GetCurrentProcess().SessionId
|
|
88
|
+
$s = Get-CimInstance Win32_Process ''' + filter + '''| Format-Table -Property @(
|
|
89
|
+
@{ Name='PID'; Expression = { $_.ProcessId }}
|
|
90
|
+
@{ Name='COMMAND'; Expression = { If ($_.CommandLine.Length) {$_.CommandLine} else {$_.Name} }}
|
|
91
|
+
) | Out-String
|
|
92
|
+
$s = $s.Trim()
|
|
93
|
+
if ($s -eq '') { exit 1 }
|
|
94
|
+
$s
|
|
95
|
+
''').replace('\n', '\r\n')
|
|
96
|
+
|
|
97
|
+
cmd = [powershell, '-NonInteractive', '-NoLogo', '-Command', '-']
|
|
98
|
+
proc = subprocess.run(cmd, input=input, encoding='utf-8', check=False)
|
|
99
|
+
return proc.returncode
|
|
100
|
+
|
|
101
|
+
def main():
|
|
102
|
+
"""script entry point"""
|
|
103
|
+
|
|
104
|
+
parser = argparse.ArgumentParser(
|
|
105
|
+
prog='processtitle',
|
|
106
|
+
description='Portably lists process IDs and their titles'
|
|
107
|
+
)
|
|
108
|
+
parser.add_argument('-a', '--all', action='store_true', dest='show_all',
|
|
109
|
+
help="show all (as opposed to 'some') processes. "
|
|
110
|
+
"The definition of 'some' is platform dependent.")
|
|
111
|
+
parser.add_argument('-p', '--pid', metavar='PID', type=int, nargs='+', dest='pids',
|
|
112
|
+
help='limit output to these process IDs')
|
|
113
|
+
parser.add_argument('-v', '--version', action='version', version=f'%(prog)s {__version__}')
|
|
114
|
+
|
|
115
|
+
args = parser.parse_args()
|
|
116
|
+
|
|
117
|
+
if not sys.platform.startswith("win32"):
|
|
118
|
+
return _do_unix(args)
|
|
119
|
+
else:
|
|
120
|
+
return _do_win(args)
|
|
121
|
+
|
|
122
|
+
if __name__ == '__main__':
|
|
123
|
+
sys.exit(main())
|
|
Binary file
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Copyright (c) 2026, Eugene Gershnik
|
|
2
|
+
# SPDX-License-Identifier: BSD-3-Clause
|
|
3
|
+
|
|
4
|
+
def prepare(*, fork_safe_only: bool = False) -> None:
|
|
5
|
+
"""Initialize the library
|
|
6
|
+
|
|
7
|
+
This method must be called prior to any calls to set_to.
|
|
8
|
+
All arguments are optional and can be used on any platform even if
|
|
9
|
+
they control something irrelevant to that platform. Such arguments
|
|
10
|
+
are simply ignored.
|
|
11
|
+
|
|
12
|
+
Args:
|
|
13
|
+
fork_safe_only: use only such external libraries and/or APIs that
|
|
14
|
+
are safe if your process later performs a `fork` without `exec`.
|
|
15
|
+
Currently this is only relevant on macOS where usage of Launch
|
|
16
|
+
Services API is **not** fork-safe and will cause crashes if used
|
|
17
|
+
together with forks without exec.
|
|
18
|
+
"""
|
|
19
|
+
...
|
|
20
|
+
|
|
21
|
+
def set_to(title: str) -> bool:
|
|
22
|
+
"""Set process title
|
|
23
|
+
|
|
24
|
+
Args:
|
|
25
|
+
title: the title to set. While an empty string or a string consisting only
|
|
26
|
+
of space characters are all legal values for this argument, their effect
|
|
27
|
+
on `ps` or other process display is unspecified and best avoided.
|
|
28
|
+
Similarly emojis or other advanced Unicode features might or might not
|
|
29
|
+
show correctly in `ps` or other output.
|
|
30
|
+
|
|
31
|
+
Returns:
|
|
32
|
+
whether the title was successfully set. On unsupported platforms
|
|
33
|
+
always returns False. Note that "success" only implies that at least one
|
|
34
|
+
method supported by the platform was fully functional, used and did not report
|
|
35
|
+
any errors.
|
|
36
|
+
Whether the title you observe will actually change as a result may depend on
|
|
37
|
+
many other factors.
|
|
38
|
+
"""
|
|
39
|
+
...
|
|
40
|
+
|
|
41
|
+
def last_set() -> str | None:
|
|
42
|
+
"""Returns last successfully set title, if any
|
|
43
|
+
|
|
44
|
+
Returns None if `set_to` was never called before.
|
|
45
|
+
"""
|
|
46
|
+
...
|
processtitle/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: processtitle
|
|
3
|
+
Version: 1.3
|
|
4
|
+
Summary: Customize process "title" as reported by ps and similar tools
|
|
5
|
+
Author-email: Eugene Gershnik <gershnik@hotmail.com>
|
|
6
|
+
License-Expression: BSD-3-Clause
|
|
7
|
+
Project-URL: Homepage, https://github.com/gershnik/processtitle
|
|
8
|
+
Project-URL: Documentation, https://github.com/gershnik/processtitle
|
|
9
|
+
Project-URL: Issues, https://github.com/gershnik/processtitle/issues
|
|
10
|
+
Project-URL: Changelog, https://github.com/gershnik/processtitle/blob/master/CHANGELOG.md
|
|
11
|
+
Keywords: setproctitle,proctitle,process title,process name
|
|
12
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
13
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
14
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
15
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
16
|
+
Classifier: Operating System :: POSIX :: BSD :: FreeBSD
|
|
17
|
+
Classifier: Operating System :: POSIX :: BSD :: NetBSD
|
|
18
|
+
Classifier: Operating System :: POSIX :: BSD :: OpenBSD
|
|
19
|
+
Classifier: Operating System :: POSIX :: SunOS/Solaris
|
|
20
|
+
Classifier: Intended Audience :: Developers
|
|
21
|
+
Classifier: Topic :: Software Development
|
|
22
|
+
Classifier: Programming Language :: C++
|
|
23
|
+
Classifier: Programming Language :: Python
|
|
24
|
+
Classifier: Programming Language :: Python :: 3
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
28
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
29
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
30
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
31
|
+
Classifier: Typing :: Typed
|
|
32
|
+
Requires-Python: >=3.10
|
|
33
|
+
Description-Content-Type: text/markdown
|
|
34
|
+
License-File: LICENSE
|
|
35
|
+
License-File: Acknowledgments.md
|
|
36
|
+
Dynamic: license-file
|
|
37
|
+
|
|
38
|
+
# processtitle
|
|
39
|
+
|
|
40
|
+
[](https://opensource.org/licenses/BSD-3-Clause)
|
|
41
|
+
[](https://www.python.org/downloads/release/python-3100/)
|
|
42
|
+
[](https://pypi.org/project/processtitle)
|
|
43
|
+
[](https://pepy.tech/projects/processtitle)
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
This Python extension module allows you to customize the process "title" as reported by `ps`, `top`, Activity Monitor,
|
|
47
|
+
Task Manager and similar tools.
|
|
48
|
+
|
|
49
|
+
It is similar to the well-known [py-setproctitle](https://github.com/dvarrazzo/py-setproctitle) module but,
|
|
50
|
+
not being constrained by backward compatibility, does things a bit differently - and hopefully
|
|
51
|
+
more conveniently - for the user. (If you are already familiar with `py-setproctitle`, make sure to read the [differences from py-setproctitle](#differences-from-py-setproctitle) section.)
|
|
52
|
+
|
|
53
|
+
Modifying the process title is useful in many cases. When you have many Python scripts, or worse, many instances of the
|
|
54
|
+
same Python script running on your system, it is very hard to understand which one is which, if all you see in your process list
|
|
55
|
+
is "Python" or "python3 same-script". Using this module allows your script to specify _what it is for_ or _what it is doing_
|
|
56
|
+
to be shown in the process list instead.
|
|
57
|
+
|
|
58
|
+
<!-- TOC depthfrom:2 -->
|
|
59
|
+
|
|
60
|
+
- [Platform support](#platform-support)
|
|
61
|
+
- [Requirements](#requirements)
|
|
62
|
+
- [Installing](#installing)
|
|
63
|
+
- [Usage](#usage)
|
|
64
|
+
- [Thread and other safety](#thread-and-other-safety)
|
|
65
|
+
- [Differences from py-setproctitle](#differences-from-py-setproctitle)
|
|
66
|
+
- [Platform details](#platform-details)
|
|
67
|
+
- [Linux](#linux)
|
|
68
|
+
- [macOS](#macos)
|
|
69
|
+
- [Windows](#windows)
|
|
70
|
+
- [BSDs](#bsds)
|
|
71
|
+
- [Illumos](#illumos)
|
|
72
|
+
|
|
73
|
+
<!-- /TOC -->
|
|
74
|
+
|
|
75
|
+
## Platform support
|
|
76
|
+
|
|
77
|
+
The module will happily _run_ and do nothing on any [compatible system](#requirements), but the systems where it
|
|
78
|
+
actually _works_ (i.e. changes the process title) are: Linux, macOS, Windows, {Free|Net|Open|DragonFly}BSD and Illumos. See
|
|
79
|
+
[platform details](#platform-details) below for more information about each platform.
|
|
80
|
+
|
|
81
|
+
In all cases, only reasonably recent versions of each platform are supported. No attempt is made to work
|
|
82
|
+
on ancient Linux kernels, Windows XP etc. etc. If you are stuck with a very old system, your best bet is
|
|
83
|
+
[py-setproctitle](https://github.com/dvarrazzo/py-setproctitle).
|
|
84
|
+
|
|
85
|
+
## Requirements
|
|
86
|
+
|
|
87
|
+
* Python >= 3.10, capable of loading native extensions. In particular, CPython, PyPy and GraalPy are all supported.
|
|
88
|
+
* If your platform doesn't have a binary wheel available, you will need:
|
|
89
|
+
* A C++ compiler capable of compiling C++20 (GCC 10.2 or above and CLang 13 or above are known to work)
|
|
90
|
+
* Python development libraries available (like `python3-dev` package in most Linux distributions)
|
|
91
|
+
|
|
92
|
+
## Installing
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
pip install processtitle
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Usage
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
import processtitle
|
|
102
|
+
|
|
103
|
+
processtitle.prepare(...optional config params...)
|
|
104
|
+
|
|
105
|
+
if not processtitle.set_to("my fancy process"):
|
|
106
|
+
print("oops, process title couldn't be set")
|
|
107
|
+
else:
|
|
108
|
+
print(f"last set process title is {processtitle.last_set()}")
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The `processtitle.prepare` currently has the following keyword-only optional parameters defined:
|
|
112
|
+
|
|
113
|
+
`fork_safe_only: bool = False`
|
|
114
|
+
: use only such external libraries and/or APIs that
|
|
115
|
+
are safe if your process later performs a `fork` **without** `exec`.
|
|
116
|
+
Currently this is only relevant on macOS where APIs needed to update title in Activity Monitor
|
|
117
|
+
are **not** fork-safe and will cause crashes if used together with `fork` without `exec`.
|
|
118
|
+
|
|
119
|
+
If you wish to enable debug output from this module you can use standard `logging` machinery:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
import logging
|
|
123
|
+
|
|
124
|
+
logging.basicConfig(...)
|
|
125
|
+
logging.getLogger("processtitle").setLevel(logging.DEBUG)
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Alternatively, you can use a `py-setproctitle`-compatible method by setting `SPT_DEBUG` environment variable
|
|
129
|
+
to a non-empty value (which is not "0"). For example:
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
SPT_DEBUG=1 your_script_that_uses_processtitle
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
For troubleshooting and general convenience you can also call the module directly or via a wrapper script:
|
|
136
|
+
```console
|
|
137
|
+
$ processtitle
|
|
138
|
+
$ #or
|
|
139
|
+
$ python3 -m processtitle
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
This produces a list of process IDs and their titles by delegating to `ps` or Windows PowerShell in a way
|
|
143
|
+
most appropriate to each platform. Run `processtitle -h` to see the available command line options.
|
|
144
|
+
|
|
145
|
+
## Thread and other safety
|
|
146
|
+
|
|
147
|
+
`processtitle` _itself_ is thread-safe - all its operations are protected by a mutex. However,
|
|
148
|
+
_the effects_ of changing process title are not. On every platform, changing the title modifies
|
|
149
|
+
some global process information. If this information is accessed by another thread at the same
|
|
150
|
+
time, Bad Things Will Happen. Therefore, it is advisable to only change the title before other
|
|
151
|
+
threads are running or when you are absolutely sure they are suspended.
|
|
152
|
+
|
|
153
|
+
On some platforms, `processtitle` modifies pointers visible to native code (for example `argv[1]...` and
|
|
154
|
+
`environ` on many Unix systems). It never deallocates the memory pointed to by these, so any native code that
|
|
155
|
+
uses cached values of such pointers should be safe. Python's `sys.argv` and `os.environ` should be
|
|
156
|
+
completely unaffected by any of these manipulations.
|
|
157
|
+
|
|
158
|
+
|
|
159
|
+
## Differences from py-setproctitle
|
|
160
|
+
|
|
161
|
+
The most notable difference between `processtitle` and `py-setproctitle` is that this library requires you
|
|
162
|
+
to call `processtitle.prepare()` before setting the process title. Absolutely nothing is done prior to `prepare` -
|
|
163
|
+
just importing the module has no side effects. The `prepare()` method arguments allow you to customize library
|
|
164
|
+
behavior on platforms where multiple incompatible behaviors are possible. Currently this affects only macOS
|
|
165
|
+
(see [macOS details](#macos) below) but in the future might be extended to other platforms.
|
|
166
|
+
|
|
167
|
+
In addition:
|
|
168
|
+
|
|
169
|
+
* There is **no** requirement to import `processtitle` as early as possible. It does
|
|
170
|
+
not rely on Python interpreter state which may be changed by other libraries
|
|
171
|
+
* There is no general "get process title" call (instead you can query the last title _you set_ via `last_set()`).
|
|
172
|
+
This is because querying the original title might not be possible on some platforms.
|
|
173
|
+
* Currently there are no "set/get _thread_ title" calls. If there is any interest, they may be added in the future.
|
|
174
|
+
* `processtitle` supports Windows. At the time of this writing `py-setproctitle` does not.
|
|
175
|
+
* Wherever possible `processtitle` avoids tinkering with `argv` and relies on other safer, documented or
|
|
176
|
+
semi-documented methods.
|
|
177
|
+
* `processtitle` uses standard Python `logging` module to produce diagnostic output rather than just printing to
|
|
178
|
+
`stdout`. (For compatibility, `SPT_DEBUG` environment variable is also supported - it simply sets the default
|
|
179
|
+
logging level for this module to `logging.DEBUG`)
|
|
180
|
+
* `processtitle` is written in C++, not C, so it requires a reasonably modern C++ compiler when binary wheels
|
|
181
|
+
are not available.
|
|
182
|
+
* `processtitle` does not support old or no longer maintained operating systems like AIX, HP-UX etc.
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
## Platform details
|
|
186
|
+
|
|
187
|
+
### Linux
|
|
188
|
+
|
|
189
|
+
On Linux you will be able to see the process title in the output of `ps` or `top` commands, as well as with any other
|
|
190
|
+
tool that displays process info.
|
|
191
|
+
|
|
192
|
+
To change the title, `processtitle` uses the following methods:
|
|
193
|
+
* [PR_SET_MM](https://www.man7.org/linux/man-pages/man2/PR_SET_MM.2const.html) call.
|
|
194
|
+
* [PR_SET_NAME](https://www.man7.org/linux/man-pages/man2/PR_SET_NAME.2const.html) call.
|
|
195
|
+
|
|
196
|
+
`processtitle.set_to()` returns `True` if at least one of these methods succeeded.
|
|
197
|
+
|
|
198
|
+
### macOS
|
|
199
|
+
|
|
200
|
+
On macOS there are 2 independent places where process title is shown: `ps`, `top` and similar commands and
|
|
201
|
+
Activity Monitor. They take information from completely different places and modifying one doesn't modify the
|
|
202
|
+
other. Unfortunately, the API required to change the title for Activity Monitor **cannot be used if your process
|
|
203
|
+
later `fork()`-s without exec()**. If used in such a process, the forked process will most likely crash randomly and
|
|
204
|
+
unpredictably. Note that some popular libraries such as `gunicorn` may use fork() internally.
|
|
205
|
+
|
|
206
|
+
> [!IMPORTANT]
|
|
207
|
+
> Using fork without exec in Python on macOS (or any other platform) is, in general, dangerous because you rarely know
|
|
208
|
+
> for sure whether the libraries your code depends upon are fork-safe. This is why the `multiprocessing` library
|
|
209
|
+
> [avoids fork by default](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods)
|
|
210
|
+
> on macOS and, recently, on all platforms.
|
|
211
|
+
|
|
212
|
+
Because of this issue, if you must use fork() on macOS you have two options:
|
|
213
|
+
|
|
214
|
+
1. Pass `fork_safe_only=True` argument to `processtitle.prepare()` in the parent process. Doing so will prevent
|
|
215
|
+
use of any non-fork-safe APIs but will also preclude customized process title from being shown in Activity Monitor.
|
|
216
|
+
|
|
217
|
+
2. Alternatively, if feasible, call `processtitle.prepare()` **after** the last `fork()` in the parent process.
|
|
218
|
+
|
|
219
|
+
To change the title, `processtitle` uses the following methods:
|
|
220
|
+
* Changing the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
|
|
221
|
+
* If `fork_safe_only` is `False` undocumented Launch Services calls
|
|
222
|
+
|
|
223
|
+
`processtitle.set_to()` returns `True` if at least one of these methods succeeded.
|
|
224
|
+
|
|
225
|
+
### Windows
|
|
226
|
+
|
|
227
|
+
On Windows you can see the process name by looking at the process command line. You can see the command lines of running
|
|
228
|
+
processes in three ways:
|
|
229
|
+
|
|
230
|
+
1. Using PowerShell's `Get-WmiObject Win32_Process` call:
|
|
231
|
+
```powershell
|
|
232
|
+
Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine
|
|
233
|
+
```
|
|
234
|
+
If you use `cmd` as your command interpreter you can achieve the same effect via:
|
|
235
|
+
```bat
|
|
236
|
+
powershell -c "Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine"
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
2. Using `processtitle` command line utility installed with this package. Run `processtitle -h` for
|
|
240
|
+
details of available switches. The utility internally uses WMI but in a more sophisticated way.
|
|
241
|
+
|
|
242
|
+
3. In Task Manager details view. If the "Command Line" column is not present, right-click the columns header,
|
|
243
|
+
choose "Select columns" and check "Command Line" entry in the list.
|
|
244
|
+
|
|
245
|
+
> [!IMPORTANT]
|
|
246
|
+
> Task Manager caches the command line of the process. If you had Task Manager open and showing the command
|
|
247
|
+
> line and *then* changed it, you might need to restart it to show the updated value.
|
|
248
|
+
|
|
249
|
+
To change the title, `processtitle` modifies/replaces partially-documented [RTL_USER_PROCESS_PARAMETERS](https://learn.microsoft.com/en-us/windows/win32/api/winternl/ns-winternl-rtl_user_process_parameters) via undocumented or partially documented calls.
|
|
250
|
+
|
|
251
|
+
### BSDs
|
|
252
|
+
|
|
253
|
+
On {Free|Net|Open|DragonFly}BSD you will be able to see the process title in the output of `ps` or `top` commands, as well
|
|
254
|
+
as with any other tool that displays process info. All of these platforms will, in general, add the original
|
|
255
|
+
executable name (e.g. `python3`) to the actual title either as a prefix or a suffix.
|
|
256
|
+
|
|
257
|
+
> [!NOTE]
|
|
258
|
+
> At the time of this writing the default compiler on DragonFly BSD is an ancient GCC 8. You will need to install
|
|
259
|
+
> GCC 11 (available as a binary package) in order to build `processtitle`. Once installed:
|
|
260
|
+
> `CC=gcc11 CXX=g++11 pip install processtitle`
|
|
261
|
+
|
|
262
|
+
To change the title, `processtitle` uses documented `setproctitle()` call ([FreeBSD](https://man.freebsd.org/cgi/man.cgi?query=setproctitle&sektion=3&format=html), [NetBSD](https://man.netbsd.org/NetBSD-10.1/setproctitle.3), [OpenBSD](https://man.openbsd.org/setproctitle.3), [DragonFly](https://man.dragonflybsd.org/?command=setproctitle)).
|
|
263
|
+
|
|
264
|
+
|
|
265
|
+
### Illumos
|
|
266
|
+
|
|
267
|
+
On Illumos by default the `ps` command shows process title captured at process creation. To see the current one pass
|
|
268
|
+
the `-F` [option](https://man.omnios.org/man1/ps).
|
|
269
|
+
|
|
270
|
+
To change the title, `processtitle` changes the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
|
|
271
|
+
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
processtitle/__init__.py,sha256=prJOe1NUUAhRzfnX81ra8ygpHMnKoYwwjIRYyBuTwwI,274
|
|
2
|
+
processtitle/__main__.py,sha256=fEe-cVcTk4mWoK9NRDg9XmbvSXM5B_hbyfAbNQFE76o,3939
|
|
3
|
+
processtitle/_processtitle.cp315-win_arm64.pyd,sha256=PxV-WSmFyhOKWqU8u9P2rQLZueh9snmJIrk8W4PVpxQ,36352
|
|
4
|
+
processtitle/_processtitle.pyi,sha256=8OOYIBFxke9MkoPR95TQat_5hZepXpH1kJ3Z-7C9_Qk,1834
|
|
5
|
+
processtitle/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
processtitle-1.3.dist-info/licenses/Acknowledgments.md,sha256=WeYuLBrhrcEcr_5q41vKwwGpeAdl2fJOm0Bj0wP7Y7Q,4325
|
|
7
|
+
processtitle-1.3.dist-info/licenses/LICENSE,sha256=8KpQ5Kn7_Ra9t1P1EoDXtkW1T4PGOCdKlXfqPkYu6Bs,1552
|
|
8
|
+
processtitle-1.3.dist-info/METADATA,sha256=UHTkTZwyVHoDTnO_a74fD39sbCo1YTgxsxhOQn9IKIs,13934
|
|
9
|
+
processtitle-1.3.dist-info/WHEEL,sha256=g1f1kqn4IVvU4p3uh1e39gJzHxbtC9umA5gNjEXIByA,101
|
|
10
|
+
processtitle-1.3.dist-info/entry_points.txt,sha256=e-8AnZQI0CMPKg3R7XvSoO4qmiyQBzDmHh2p4Ag0vgE,60
|
|
11
|
+
processtitle-1.3.dist-info/top_level.txt,sha256=SqJ1DGfZ2snETH8CuvV4Ffiy1ElG_zaFevnAxMAKBUM,13
|
|
12
|
+
processtitle-1.3.dist-info/RECORD,,
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# Acknowledgements
|
|
2
|
+
|
|
3
|
+
**processtitle** contains code derived from the open source software listed below.
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
## [intrusive_shared_ptr](https://github.com/gershnik/intrusive_shared_ptr)
|
|
7
|
+
|
|
8
|
+
Distributed under MIT License
|
|
9
|
+
|
|
10
|
+
----
|
|
11
|
+
```
|
|
12
|
+
MIT License
|
|
13
|
+
|
|
14
|
+
Copyright (c) 2004 Eugene Gershnik
|
|
15
|
+
|
|
16
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
17
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
18
|
+
in the Software without restriction, including without limitation the rights
|
|
19
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
20
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
21
|
+
furnished to do so, subject to the following conditions:
|
|
22
|
+
|
|
23
|
+
The above copyright notice and this permission notice shall be included in all
|
|
24
|
+
copies or substantial portions of the Software.
|
|
25
|
+
|
|
26
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
27
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
28
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
29
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
30
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
31
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
32
|
+
SOFTWARE.
|
|
33
|
+
```
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## [libbsd setproctitle](https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/main/src/setproctitle.c)
|
|
37
|
+
|
|
38
|
+
Distributed under MIT License
|
|
39
|
+
|
|
40
|
+
----
|
|
41
|
+
```
|
|
42
|
+
Copyright © 2010 William Ahern
|
|
43
|
+
Copyright © 2012 Guillem Jover <guillem@hadrons.org>
|
|
44
|
+
|
|
45
|
+
Permission is hereby granted, free of charge, to any person obtaining a
|
|
46
|
+
copy of this software and associated documentation files (the
|
|
47
|
+
"Software"), to deal in the Software without restriction, including
|
|
48
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
|
49
|
+
distribute, sublicense, and/or sell copies of the Software, and to permit
|
|
50
|
+
persons to whom the Software is furnished to do so, subject to the
|
|
51
|
+
following conditions:
|
|
52
|
+
|
|
53
|
+
The above copyright notice and this permission notice shall be included
|
|
54
|
+
in all copies or substantial portions of the Software.
|
|
55
|
+
|
|
56
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
|
|
57
|
+
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
58
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
|
|
59
|
+
NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
|
|
60
|
+
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
|
|
61
|
+
OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
|
|
62
|
+
USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
63
|
+
```
|
|
64
|
+
----
|
|
65
|
+
|
|
66
|
+
## [py-setproctitle](https://github.com/dvarrazzo/py-setproctitle)
|
|
67
|
+
|
|
68
|
+
Distributed under BSD 3-Clause License
|
|
69
|
+
|
|
70
|
+
----
|
|
71
|
+
```
|
|
72
|
+
BSD 3-Clause License
|
|
73
|
+
|
|
74
|
+
Copyright (c) 2009, Daniele Varrazzo <daniele.varrazzo@gmail.com>
|
|
75
|
+
|
|
76
|
+
Redistribution and use in source and binary forms, with or without
|
|
77
|
+
modification, are permitted provided that the following conditions are met:
|
|
78
|
+
|
|
79
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
80
|
+
list of conditions and the following disclaimer.
|
|
81
|
+
|
|
82
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
83
|
+
this list of conditions and the following disclaimer in the documentation
|
|
84
|
+
and/or other materials provided with the distribution.
|
|
85
|
+
|
|
86
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
87
|
+
contributors may be used to endorse or promote products derived from
|
|
88
|
+
this software without specific prior written permission.
|
|
89
|
+
|
|
90
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
91
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
92
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
93
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
94
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
95
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
96
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
97
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
98
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
99
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
100
|
+
```
|
|
101
|
+
----
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026, Eugene Gershnik
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
1. Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
2. Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
3. Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
processtitle
|