processtitle 0.1.0__tar.gz

processtitle-0.1.0/Acknowledgments.md

@@ -0,0 +1,101 @@
+# Acknowledgements
+
+**processtitle** contains code derived from the open source software listed below.
+
+
+## [intrusive_shared_ptr](https://github.com/gershnik/intrusive_shared_ptr)
+
+Distributed under MIT License
+
+----
+```
+MIT License
+
+Copyright (c) 2004 Eugene Gershnik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+---
+
+## [libbsd setproctitle](https://gitlab.freedesktop.org/libbsd/libbsd/-/blob/main/src/setproctitle.c)
+
+Distributed under MIT License
+
+----
+```
+Copyright © 2010 William Ahern
+Copyright © 2012 Guillem Jover <guillem@hadrons.org>
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit
+persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN
+NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.
+```
+----
+
+## [py-setproctitle](https://github.com/dvarrazzo/py-setproctitle)
+
+Distributed under BSD 3-Clause License
+
+----
+```
+BSD 3-Clause License
+
+Copyright (c) 2009, Daniele Varrazzo <daniele.varrazzo@gmail.com>
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+----

processtitle-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Eugene Gershnik
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

processtitle-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include src/cpp *.h *.cpp 
+exclude tests/**

processtitle-0.1.0/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.4
+Name: processtitle
+Version: 0.1.0
+Summary: Customize process "title" as reported by ps and similar tools
+Author-email: Eugene Gershnik <gershnik@hotmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/gershnik/processtitle
+Project-URL: Documentation, https://github.com/gershnik/processtitle
+Project-URL: Issues, https://github.com/gershnik/processtitle/issues
+Project-URL: Changelog, https://github.com/gershnik/processtitle/blob/master/CHANGELOG.md
+Keywords: setproctitle,proctitle,process title,process name
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: BSD :: FreeBSD
+Classifier: Operating System :: POSIX :: BSD :: NetBSD
+Classifier: Operating System :: POSIX :: BSD :: OpenBSD
+Classifier: Operating System :: POSIX :: SunOS/Solaris
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development
+Classifier: Programming Language :: C++
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: Acknowledgments.md
+Dynamic: license-file
+
+# processtitle
+
+This Python extension module allows you to customize process "title" as reported by `ps`, `top`, Activity Monitor,
+Task Manager and similar tools.
+
+It is similar to the well known [py-setproctitle](https://github.com/dvarrazzo/py-setproctitle) module but,
+not being constrained by backward compatibility, does things a bit differently and, hopefully, makes things more convenient
+for a user. (If you are already familiar with `py-setproctitle` make sure to read [differences from py-setproctitle](#differences-from-py-setproctitle) section.)
+
+Modifying process title is useful in many cases. When you have many Python scripts, or, worse, many instances of the
+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
+is "Python" or "python3 same-script". Using this module allows your script to specify _what it is for_ or _what it is doing_
+to be shown in the process list instead.
+
+<!-- TOC depthfrom:2 -->
+
+- [Platform support](#platform-support)
+- [Requirements](#requirements)
+- [Installing](#installing)
+- [Usage](#usage)
+- [Thread and other safety](#thread-and-other-safety)
+- [Differences from py-setproctitle](#differences-from-py-setproctitle)
+- [Platform details](#platform-details)
+    - [Linux](#linux)
+    - [macOS](#macos)
+    - [Windows](#windows)
+    - [BSDs](#bsds)
+    - [Illumos](#illumos)
+
+<!-- /TOC -->
+
+## Platform support
+
+The module will happily _run_ and do nothing on any [compatible system](#requirements) but the ones where it 
+actually _works_ (i.e. changes the process title) are: Linux, macOS, Windows, {Free|Net|Open}BSD and Illumos. See 
+[platform details](#platform-details) below for more information about each platform.
+
+In all cases only reasonably recent versions of each platform are supported. No attempt is made to work
+on ancient Linux kernels, Windows XP etc. etc. If you are stuck with a very old system your best bet is 
+[py-setproctitle](https://github.com/dvarrazzo/py-setproctitle).
+
+## Requirements
+
+* Python >= 3.10 capable of loading native extensions
+* If your platform doesn't have a binary wheel available, you will need:
+  * A C++ compiler capable of compiling C++20 (GCC 10.2 or above and CLang 13 or above are known to work)
+  * Python development libraries available (like `python3-dev` package in most Linux distributions)
+
+## Installing
+
+```bash
+pip install processtitle
+```
+
+## Usage
+
+```python
+import processtitle
+
+processtitle.prepare(...optional config params...)
+
+if not processtitle.set_to("my fancy process"):
+    print("ooops, process title couldn't be set")
+else:
+    print(f"last set process title is {processtitle.last_set()}")
+```
+
+The `processtitle.prepare` currently has the following keyword-only optional parameters defined:
+
+`fork_safe_only: bool = False`
+: use only such external libraries and/or APIs that
+  are safe if your process later performs a `fork` **without** `exec`.
+  Currently this is only relevant on macOS where APIs needed to update title in Activity Monitor 
+  are **not** fork-safe and will cause crashes if used together with `fork` without `exec`. 
+
+If you wish to enable debug output from this module you can use standard `logging` machinery:
+
+```python
+import logging
+
+logging.basicConfig(...)
+logging.getLogger("processtitle").setLevel(logging.DEBUG)
+```
+
+Alternatively, you can use `py-setproctitle` compatible method by setting `SPT_DEBUG` environment variable
+to a non-empty value (which is not "0"). For example:
+
+```bash
+SPT_DEBUG=1 your_script_that_uses_processtitle
+```
+
+## Thread and other safety
+
+`processtitle` _itself_ is thread-safe - all its operations are protected by a mutex. However, 
+_the effects_ of changing process title are not. On every platform, changing the title modifies
+some globals process information. If this information is accessed by another thread at the same
+time Bad Things Will Happen. Therefore, it is advisable to only change the title before other
+threads are running or when you are absolutely sure they are suspended.
+
+On some platforms, `processtitle` modifies pointers visible to native code (for example `argv[1]...` and 
+`environ` on many Unix systems). It never deallocates the memory pointed by these so any native code that 
+uses cached values of such pointer should be safe. Python's `sys.argv` and `os.environ` should be 
+completely unaffected by any of these manipulations.
+
+
+## Differences from py-setproctitle
+
+The most notable difference between `processtitle` and `py-setproctitle` is that this library requires you 
+to call `processtitle.prepare()` before setting the process title. Absolutely nothing is done prior to `prepare` - 
+just importing the module has no side effects. The `prepare()` method arguments allow you to customize library 
+behavior on platforms where multiple incompatible behaviors are possible. Currently this affects only macOS 
+(see [macOS details](#macos) below) but in the future might be extended to other platforms.
+
+In addition:
+
+* There is **no** requirement to import `processtitle` as early as possible. It does
+  not rely on Python interpreter state which may be changed by other libraries
+* There is no general "get process title" call (instead you can query the last title _you set_ via `last_set()`).
+  This is because querying the original title might not be possible on some platforms.
+* Currently there are no "set/get _thread_ title" calls. If there is any interest, they may be added in the future.
+* `processtitle` supports Windows. At the time of this writing `py-setproctitle` does not.
+* Wherever possible `processtitle` avoids tinkering with `argv` and relies on other safer, documented or 
+  semi-documented methods.
+* `processtitle` uses standard Python `logging` module to produce diagnostic output rather than just printing to 
+  `stdout`. (For compatibility, `SPT_DEBUG` environment variable is also supported - it simply sets the default
+   logging level for this module to `logging.DEBUG`)
+* `processtitle` is written in C++, not C, so it requires a reasonably modern C++ compiler when binary wheels
+  are not available.
+* `processtitle` does not support old or no longer maintained operating systems like AIX, HP-UX etc. 
+
+
+## Platform details
+
+### Linux
+
+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
+tool that displays process info. Note that on some Linux variants (e.g. Alpine) the title might be prefixed or suffixed 
+by the original process executable name. For example: `{python3} your title`. 
+
+To change the title, `processtitle` uses the following methods:
+* [PR_SET_MM](https://www.man7.org/linux/man-pages/man2/PR_SET_MM.2const.html) call, if available and works. 
+* Otherwise [PR_SET_NAME](https://www.man7.org/linux/man-pages/man2/PR_SET_NAME.2const.html)
+
+
+### macOS
+
+On macOS there are 2 independent places where process title is shown: `ps`, `top` and similar commands and
+Activity Monitor. They take information from completely different places and modifying one doesn't modify the
+other. Unfortunately, the API required to change the title for Activity Monitor **cannot be used if your process
+later fork()-s without exec()**. If used in such a process, the forked process will most likely crash randomly and
+unpredictably. Note that some popular libraries such as `gunicorn` may use fork() internally.
+
+> [!IMPORTANT]
+> Using fork without exec in Python on macOS (or any other platform) is, in general, dangerous because you rarely know
+> for sure whether the libraries your code depends upon are fork-safe. This is why `multiprocessing` library
+> [avoids fork by default](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods)
+> on macOS and, recently, on all platforms.
+
+Because of this issue, if you must use fork() on macOS you have two options:
+
+1. Pass `fork_safe_only=True` argument to `processtitle.prepare()` in the parent process. Doing so will prevent 
+  use of any non-fork-safe APIs but will also preclude customized process title from being shown in Activity Monitor.
+
+2. Alternatively, if feasible, call `processtitle.prepare()` **after** the last `fork()` in the parent process. 
+
+To change the title, `processtitle` uses the following methods:
+* Changing the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
+* If `fork_safe_only` is `False` undocumented Launch Services calls
+
+
+### Windows
+
+On Windows you can see the process by looking at the process command line. You can see the command lines of running 
+processes in two ways:
+
+1. Using powershell's `Get-WmiObject Win32_Process` call:
+  ```powershell
+  Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine
+  ```
+  If you use `cmd` as your command interpreter you can achieve the same effect via:
+  ```bat
+  powershell -c "Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine"
+  ```
+
+2. In Task Manager details view. If the "Command Line" column is not present, right-click the columns header,
+  choose "Select columns" and check "Command Line" entry in the list.
+
+To change the title, `processtitle` uses 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.
+
+### BSDs
+
+On {Free|Net|Open}BSD you will be able to see the process title in the output of `ps` or `top` commands, as well, 
+as with any other tool that displays process info. All of these platforms will, in general, add the original 
+executable name (e.g. `python3`) to the actual title either as a prefix or a suffix.
+
+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)). 
+
+
+### Illumos
+
+On Illumos by default the `ps` command shows process title captured at process creation. To see the current one pass
+the `-F` [option](https://man.omnios.org/man1/ps).
+
+To change the title, `processtitle` changes the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
+

processtitle-0.1.0/README.md

@@ -0,0 +1,205 @@
+# processtitle
+
+This Python extension module allows you to customize process "title" as reported by `ps`, `top`, Activity Monitor,
+Task Manager and similar tools.
+
+It is similar to the well known [py-setproctitle](https://github.com/dvarrazzo/py-setproctitle) module but,
+not being constrained by backward compatibility, does things a bit differently and, hopefully, makes things more convenient
+for a user. (If you are already familiar with `py-setproctitle` make sure to read [differences from py-setproctitle](#differences-from-py-setproctitle) section.)
+
+Modifying process title is useful in many cases. When you have many Python scripts, or, worse, many instances of the
+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
+is "Python" or "python3 same-script". Using this module allows your script to specify _what it is for_ or _what it is doing_
+to be shown in the process list instead.
+
+<!-- TOC depthfrom:2 -->
+
+- [Platform support](#platform-support)
+- [Requirements](#requirements)
+- [Installing](#installing)
+- [Usage](#usage)
+- [Thread and other safety](#thread-and-other-safety)
+- [Differences from py-setproctitle](#differences-from-py-setproctitle)
+- [Platform details](#platform-details)
+    - [Linux](#linux)
+    - [macOS](#macos)
+    - [Windows](#windows)
+    - [BSDs](#bsds)
+    - [Illumos](#illumos)
+
+<!-- /TOC -->
+
+## Platform support
+
+The module will happily _run_ and do nothing on any [compatible system](#requirements) but the ones where it 
+actually _works_ (i.e. changes the process title) are: Linux, macOS, Windows, {Free|Net|Open}BSD and Illumos. See 
+[platform details](#platform-details) below for more information about each platform.
+
+In all cases only reasonably recent versions of each platform are supported. No attempt is made to work
+on ancient Linux kernels, Windows XP etc. etc. If you are stuck with a very old system your best bet is 
+[py-setproctitle](https://github.com/dvarrazzo/py-setproctitle).
+
+## Requirements
+
+* Python >= 3.10 capable of loading native extensions
+* If your platform doesn't have a binary wheel available, you will need:
+  * A C++ compiler capable of compiling C++20 (GCC 10.2 or above and CLang 13 or above are known to work)
+  * Python development libraries available (like `python3-dev` package in most Linux distributions)
+
+## Installing
+
+```bash
+pip install processtitle
+```
+
+## Usage
+
+```python
+import processtitle
+
+processtitle.prepare(...optional config params...)
+
+if not processtitle.set_to("my fancy process"):
+    print("ooops, process title couldn't be set")
+else:
+    print(f"last set process title is {processtitle.last_set()}")
+```
+
+The `processtitle.prepare` currently has the following keyword-only optional parameters defined:
+
+`fork_safe_only: bool = False`
+: use only such external libraries and/or APIs that
+  are safe if your process later performs a `fork` **without** `exec`.
+  Currently this is only relevant on macOS where APIs needed to update title in Activity Monitor 
+  are **not** fork-safe and will cause crashes if used together with `fork` without `exec`. 
+
+If you wish to enable debug output from this module you can use standard `logging` machinery:
+
+```python
+import logging
+
+logging.basicConfig(...)
+logging.getLogger("processtitle").setLevel(logging.DEBUG)
+```
+
+Alternatively, you can use `py-setproctitle` compatible method by setting `SPT_DEBUG` environment variable
+to a non-empty value (which is not "0"). For example:
+
+```bash
+SPT_DEBUG=1 your_script_that_uses_processtitle
+```
+
+## Thread and other safety
+
+`processtitle` _itself_ is thread-safe - all its operations are protected by a mutex. However, 
+_the effects_ of changing process title are not. On every platform, changing the title modifies
+some globals process information. If this information is accessed by another thread at the same
+time Bad Things Will Happen. Therefore, it is advisable to only change the title before other
+threads are running or when you are absolutely sure they are suspended.
+
+On some platforms, `processtitle` modifies pointers visible to native code (for example `argv[1]...` and 
+`environ` on many Unix systems). It never deallocates the memory pointed by these so any native code that 
+uses cached values of such pointer should be safe. Python's `sys.argv` and `os.environ` should be 
+completely unaffected by any of these manipulations.
+
+
+## Differences from py-setproctitle
+
+The most notable difference between `processtitle` and `py-setproctitle` is that this library requires you 
+to call `processtitle.prepare()` before setting the process title. Absolutely nothing is done prior to `prepare` - 
+just importing the module has no side effects. The `prepare()` method arguments allow you to customize library 
+behavior on platforms where multiple incompatible behaviors are possible. Currently this affects only macOS 
+(see [macOS details](#macos) below) but in the future might be extended to other platforms.
+
+In addition:
+
+* There is **no** requirement to import `processtitle` as early as possible. It does
+  not rely on Python interpreter state which may be changed by other libraries
+* There is no general "get process title" call (instead you can query the last title _you set_ via `last_set()`).
+  This is because querying the original title might not be possible on some platforms.
+* Currently there are no "set/get _thread_ title" calls. If there is any interest, they may be added in the future.
+* `processtitle` supports Windows. At the time of this writing `py-setproctitle` does not.
+* Wherever possible `processtitle` avoids tinkering with `argv` and relies on other safer, documented or 
+  semi-documented methods.
+* `processtitle` uses standard Python `logging` module to produce diagnostic output rather than just printing to 
+  `stdout`. (For compatibility, `SPT_DEBUG` environment variable is also supported - it simply sets the default
+   logging level for this module to `logging.DEBUG`)
+* `processtitle` is written in C++, not C, so it requires a reasonably modern C++ compiler when binary wheels
+  are not available.
+* `processtitle` does not support old or no longer maintained operating systems like AIX, HP-UX etc. 
+
+
+## Platform details
+
+### Linux
+
+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
+tool that displays process info. Note that on some Linux variants (e.g. Alpine) the title might be prefixed or suffixed 
+by the original process executable name. For example: `{python3} your title`. 
+
+To change the title, `processtitle` uses the following methods:
+* [PR_SET_MM](https://www.man7.org/linux/man-pages/man2/PR_SET_MM.2const.html) call, if available and works. 
+* Otherwise [PR_SET_NAME](https://www.man7.org/linux/man-pages/man2/PR_SET_NAME.2const.html)
+
+
+### macOS
+
+On macOS there are 2 independent places where process title is shown: `ps`, `top` and similar commands and
+Activity Monitor. They take information from completely different places and modifying one doesn't modify the
+other. Unfortunately, the API required to change the title for Activity Monitor **cannot be used if your process
+later fork()-s without exec()**. If used in such a process, the forked process will most likely crash randomly and
+unpredictably. Note that some popular libraries such as `gunicorn` may use fork() internally.
+
+> [!IMPORTANT]
+> Using fork without exec in Python on macOS (or any other platform) is, in general, dangerous because you rarely know
+> for sure whether the libraries your code depends upon are fork-safe. This is why `multiprocessing` library
+> [avoids fork by default](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods)
+> on macOS and, recently, on all platforms.
+
+Because of this issue, if you must use fork() on macOS you have two options:
+
+1. Pass `fork_safe_only=True` argument to `processtitle.prepare()` in the parent process. Doing so will prevent 
+  use of any non-fork-safe APIs but will also preclude customized process title from being shown in Activity Monitor.
+
+2. Alternatively, if feasible, call `processtitle.prepare()` **after** the last `fork()` in the parent process. 
+
+To change the title, `processtitle` uses the following methods:
+* Changing the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
+* If `fork_safe_only` is `False` undocumented Launch Services calls
+
+
+### Windows
+
+On Windows you can see the process by looking at the process command line. You can see the command lines of running 
+processes in two ways:
+
+1. Using powershell's `Get-WmiObject Win32_Process` call:
+  ```powershell
+  Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine
+  ```
+  If you use `cmd` as your command interpreter you can achieve the same effect via:
+  ```bat
+  powershell -c "Get-WmiObject Win32_Process | Select-Object ProcessId, CommandLine"
+  ```
+
+2. In Task Manager details view. If the "Command Line" column is not present, right-click the columns header,
+  choose "Select columns" and check "Command Line" entry in the list.
+
+To change the title, `processtitle` uses 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.
+
+### BSDs
+
+On {Free|Net|Open}BSD you will be able to see the process title in the output of `ps` or `top` commands, as well, 
+as with any other tool that displays process info. All of these platforms will, in general, add the original 
+executable name (e.g. `python3`) to the actual title either as a prefix or a suffix.
+
+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)). 
+
+
+### Illumos
+
+On Illumos by default the `ps` command shows process title captured at process creation. To see the current one pass
+the `-F` [option](https://man.omnios.org/man1/ps).
+
+To change the title, `processtitle` changes the content of native (not Python's) `argv[0]` (while preserving the rest of `argv` and relocating `environ`).
+

processtitle-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = [
+    "setuptools>=77.0.3",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+
+[tool.setuptools.dynamic]
+version = {attr = "processtitle.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+
+[project]
+name = "processtitle"
+dynamic = ["version"]
+authors= [
+    { name = 'Eugene Gershnik', email='gershnik@hotmail.com'}
+]
+description = 'Customize process "title" as reported by ps and similar tools'
+readme="README.md"
+license = "BSD-3-Clause"
+license-files = ["LICENSE", "Acknowledgments.md"]
+requires-python = ">=3.10"
+keywords = [
+    'setproctitle', 'proctitle', 'process title', 'process name'
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS :: MacOS X",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: BSD :: FreeBSD",
+    "Operating System :: POSIX :: BSD :: NetBSD",
+    "Operating System :: POSIX :: BSD :: OpenBSD",
+    "Operating System :: POSIX :: SunOS/Solaris",
+    
+    "Intended Audience :: Developers",
+    
+    "Topic :: Software Development",
+
+    "Programming Language :: C++",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+
+    "Typing :: Typed"
+]
+
+[project.urls]
+Homepage = 'https://github.com/gershnik/processtitle'
+Documentation = 'https://github.com/gershnik/processtitle'
+Issues = 'https://github.com/gershnik/processtitle/issues'
+Changelog = 'https://github.com/gershnik/processtitle/blob/master/CHANGELOG.md'

processtitle-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+