Skip to content

Title

provide.foundation.process.title

TODO: Add module docstring.

Functions

get_process_title 

get_process_title() -> str | None

Get the current process title.

Automatically returns None in test mode (via @skip_in_test_mode decorator) to prevent test interference.

Returns:

Type Description
str | None

The current process title, or None if setproctitle is not available
str | None

or running in test mode
Example

from provide.foundation.process import get_process_title, set_process_title set_process_title("my-process") True get_process_title() 'my-process'

Source code in provide/foundation/process/title.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
@skip_in_test_mode(return_value=None, reason="Process title queries interfere with test isolation")
def get_process_title() -> str | None:
    """Get the current process title.

    Automatically returns None in test mode (via @skip_in_test_mode decorator)
    to prevent test interference.

    Returns:
        The current process title, or None if setproctitle is not available
        or running in test mode

    Example:
        >>> from provide.foundation.process import get_process_title, set_process_title
        >>> set_process_title("my-process")
        True
        >>> get_process_title()
        'my-process'

    """
    if not _HAS_SETPROCTITLE:
        return None

    try:
        return setproctitle.getproctitle()
    except Exception as e:
        log.debug("Failed to get process title", error=str(e))
        return None

has_setproctitle 

has_setproctitle() -> bool

Check if setproctitle is available.

Returns:

Type Description
bool

True if setproctitle is available, False otherwise
Example

from provide.foundation.process import has_setproctitle if has_setproctitle(): ... # Use process title features ... pass

Source code in provide/foundation/process/title.py 
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def has_setproctitle() -> bool:
    """Check if setproctitle is available.

    Returns:
        True if setproctitle is available, False otherwise

    Example:
        >>> from provide.foundation.process import has_setproctitle
        >>> if has_setproctitle():
        ...     # Use process title features
        ...     pass

    """
    return _HAS_SETPROCTITLE

set_process_title 

set_process_title(title: str) -> bool

Set the process title visible in system monitoring tools.

The process title is what appears in ps, top, htop, and other system monitoring tools. This is useful for identifying processes, especially in multi-process applications or long-running services.

Automatically disabled in test mode (via @skip_in_test_mode decorator) to prevent interference with test isolation and parallel test execution.

Parameters:

Name Type Description Default
title str

The title to set for the current process

 required

Returns:

Type Description
bool

True if the title was set successfully (or skipped in test mode),
bool

False if setproctitle is not available
Example

from provide.foundation.process import set_process_title set_process_title("my-worker-process") True

Process will now show as "my-worker-process" in ps/top
Source code in provide/foundation/process/title.py 
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
@skip_in_test_mode(return_value=True, reason="Process title changes interfere with test isolation")
def set_process_title(title: str) -> bool:
    """Set the process title visible in system monitoring tools.

    The process title is what appears in ps, top, htop, and other system
    monitoring tools. This is useful for identifying processes, especially
    in multi-process applications or long-running services.

    Automatically disabled in test mode (via @skip_in_test_mode decorator) to
    prevent interference with test isolation and parallel test execution.

    Args:
        title: The title to set for the current process

    Returns:
        True if the title was set successfully (or skipped in test mode),
        False if setproctitle is not available

    Example:
        >>> from provide.foundation.process import set_process_title
        >>> set_process_title("my-worker-process")
        True
        >>> # Process will now show as "my-worker-process" in ps/top

    """
    if not _HAS_SETPROCTITLE:
        log.debug(
            "Cannot set process title - setproctitle not available",
            title=title,
            hint="Install with: pip install provide-foundation[process]",
        )
        return False

    try:
        setproctitle.setproctitle(title)
        log.debug("Process title set", title=title)
        return True
    except Exception as e:
        log.warning("Failed to set process title", title=title, error=str(e))
        return False

set_process_title_from_argv 

set_process_title_from_argv() -> bool

Set process title from argv, preserving the invoked command name.

Extracts the command name from sys.argv[0] (including symlinks) and formats it with the remaining arguments to create a clean process title.

This handles symlinks correctly - if you have a symlink 'whatever' pointing to 'pyvider', and run 'whatever run --config foo.yml', the process title will be 'whatever run --config foo.yml'.

Automatically disabled in test mode (via @skip_in_test_mode decorator) to prevent interference with test isolation and parallel test execution.

Returns:

Type Description
bool

True if the title was set successfully (or skipped in test mode),
bool

False if setproctitle is not available
Example
If invoked as: pyvider run --config foo.yml

from provide.foundation.process import set_process_title_from_argv set_process_title_from_argv() True

Process will show as "pyvider run --config foo.yml" in ps/top
If invoked via symlink: whatever run
(where whatever -> pyvider)

set_process_title_from_argv() True

Process will show as "whatever run" in ps/top
Source code in provide/foundation/process/title.py 
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
@skip_in_test_mode(return_value=True, reason="Process title changes interfere with test isolation")
def set_process_title_from_argv() -> bool:
    """Set process title from argv, preserving the invoked command name.

    Extracts the command name from sys.argv[0] (including symlinks) and
    formats it with the remaining arguments to create a clean process title.

    This handles symlinks correctly - if you have a symlink 'whatever' pointing
    to 'pyvider', and run 'whatever run --config foo.yml', the process title
    will be 'whatever run --config foo.yml'.

    Automatically disabled in test mode (via @skip_in_test_mode decorator) to
    prevent interference with test isolation and parallel test execution.

    Returns:
        True if the title was set successfully (or skipped in test mode),
        False if setproctitle is not available

    Example:
        >>> # If invoked as: pyvider run --config foo.yml
        >>> from provide.foundation.process import set_process_title_from_argv
        >>> set_process_title_from_argv()
        True
        >>> # Process will show as "pyvider run --config foo.yml" in ps/top

        >>> # If invoked via symlink: whatever run
        >>> # (where whatever -> pyvider)
        >>> set_process_title_from_argv()
        True
        >>> # Process will show as "whatever run" in ps/top

    """
    from pathlib import Path
    import sys

    # Extract command name from argv[0] - preserves symlink names
    cmd_name = Path(sys.argv[0]).name
    args = sys.argv[1:]

    # Format title as "cmd arg1 arg2..."
    title = f"{cmd_name} {' '.join(args)}" if args else cmd_name

    return set_process_title(title)