CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-setproctitle

A Python module to customize the process title

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

setproctitle

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.

Package Information

  • Package Name: setproctitle
  • Package Type: pypi
  • Language: Python
  • Installation: pip install setproctitle

Core Imports

import setproctitle

For importing specific functions:

from setproctitle import setproctitle, getproctitle, setthreadtitle, getthreadtitle

Basic Usage

import setproctitle

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

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

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

# Get current thread title
thread_title = setproctitle.getthreadtitle()
print(f"Current thread title: {thread_title}")

Architecture

The module provides a dual-implementation architecture:

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

Capabilities

Process Title Management

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

def setproctitle(title: str) -> None:
    """
    Set title as the title for the current process.
    
    Parameters:
    - title (str): The new process title to set
    
    Returns:
    None
    
    Notes:
    The process title is visible in /proc/PID/cmdline, /proc/PID/status, 
    /proc/PID/comm files and used by tools like ps and top.
    """

def getproctitle() -> str:
    """
    Return the current process title.
    
    Parameters:
    None
    
    Returns:
    str: Current process title, or command line arguments joined by spaces
         if C extension unavailable
    """

Thread Title Management

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

def setthreadtitle(title: str) -> None:
    """
    Set title as the title for the current thread.
    
    Parameters:
    - title (str): The new thread title to set
    
    Returns:
    None
    
    Notes:
    Thread title is exposed as /proc/PID/task/TID/comm on supported platforms
    and used by tools like htop.
    """

def getthreadtitle() -> str:
    """
    Get the current thread title.
    
    Parameters:
    None
    
    Returns:
    str: Current thread title, or empty string if C extension unavailable
    """

Environment Variables

The module behavior can be customized using environment variables:

  • 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.

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

Platform-Specific Behavior

Linux

  • Uses sys/prctl.h for process title manipulation
  • Full support for both process and thread titles

BSD

  • Uses native setproctitle() system call
  • Built-in platform support with HAVE_SETPROCTITLE and HAVE_PS_STRING definitions

macOS

  • Includes darwin_set_process_name.c for platform-specific implementation
  • Automatic initialization via getproctitle() call to avoid fork() issues
  • Defined with __darwin__ symbol

Windows

  • Creates Named Objects readable by Process Explorer
  • No actual process title change capability
  • Process title changes are visible through specialized monitoring tools

Error Handling

The module provides graceful degradation:

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

Usage Examples

Multi-process Application

import os
import setproctitle
from multiprocessing import Process

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

if __name__ == "__main__":
    # Set main process title
    setproctitle.setproctitle("myapp-master")
    
    # Start worker processes
    processes = []
    for i in range(3):
        p = Process(target=worker_process, args=(i,))
        p.start()
        processes.append(p)
    
    # Wait for all workers
    for p in processes:
        p.join()

Thread Title Management

import threading
import setproctitle

def worker_thread(thread_name):
    # Set thread title for monitoring
    setproctitle.setthreadtitle(f"worker-{thread_name}")
    
    # Do thread work...
    print(f"Thread {thread_name} title: {setproctitle.getthreadtitle()}")

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

# Wait for completion
for t in threads:
    t.join()
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/setproctitle@1.3.x
Publish Source
CLI
Badge
tessl/pypi-setproctitle badge