Go to the latest version of this document.

# ``twisted`.`python`.`util``

module documentation
(source)

Undocumented

Class | `FancyEqMixin` | Mixin that implements `__eq__` and `__ne__`.
Class | `FancyStrMixin` | Mixin providing a flexible implementation of `__str__`.
Class | `InsensitiveDict` | Dictionary, that has case-insensitive keys.
Class | `IntervalDifferential` | Given a list of intervals, generate the amount of time to sleep between "instants".
Class | `LineLog` | A limited-size line-based log, useful for logging line-based protocols such as SMTP.
Function | `addPluginDir` | Undocumented
Function | `getPassword` | Obtain a password by prompting or from stdin.
Function | `getPluginDirs` | Undocumented
Function | `gidFromString` | Convert a group identifier, as a string, into an integer GID.
Function | `initgroups` | Do nothing.
Function | `makeStatBar` | Creates a function that will return a string representing a progress bar.
Function | `mergeFunctionMetadata` | Overwrite `g`'s name and docstring with values from `f`. Update `g`'s instance dictionary with `f`'s.
Function | `nameToLabel` | Convert a string like a variable name into a slightly more human-friendly string with spaces and capitalized letters.
Function | `padTo` | Pads a sequence out to n elements,
Function | `println` | Undocumented
Function | `raises` | Determine whether the given call raises the given exception.
Function | `runAsEffectiveUser` | Run the given function wrapped with seteuid/setegid calls.
Function | `runWithWarningsSuppressed` | Run `f(*args, **kwargs)`, but with some warnings suppressed.
Function | `searchupwards` | Walk upwards from start, looking for a directory containing all files and directories given as arguments:
Function | `sibpath` | Return the path to a sibling of a file in the filesystem.
Function | `spewer` | A trace function for sys.settrace that prints every function or method call.
Function | `str_xor` | Undocumented
Function | `switchUID` | Attempts to switch the uid/euid and gid/egid for the current process.
Function | `uidFromString` | Convert a user identifier, as a string, into an integer UID.
Function | `uniquify` | Make the elements of a list unique by inserting them into a dictionary. This must not change the order of the input lst.
Function | `untilConcludes` | Call `f` with the given arguments, handling `EINTR` by retrying.
Class | `_IntervalDifferentialIterator` | Undocumented
Function | `_getpass` | Helper to turn IOErrors into KeyboardInterrupts.
Type Variable | `_T` | Undocumented

def addPluginDir(): (source)

Undocumented

def getPassword(prompt='Password: ', confirm=0, forceTTY=0, confirmPrompt='Confirm password: ', mismatchMessage='Passwords don\'t match.'): (source)

Obtain a password by prompting or from stdin.

If stdin is a terminal, prompt for a new password, and confirm (if `confirm` is true) by asking again to make sure the user typed the same thing, as keystrokes will not be echoed.

If stdin is not a terminal, and `forceTTY` is not true, read in a line and use it as the password, less the trailing newline, if any. If `forceTTY` is true, attempt to open a tty and prompt for the password using it. Raise a RuntimeError if this is not possible.

Returns
`str`

def getPluginDirs(): (source)

Undocumented

def gidFromString(gidString): (source)

Convert a group identifier, as a string, into an integer GID.

Parameters
gidString:`str` | A string giving the base-ten representation of a GID or the name of a group which can be converted to a GID via `grp.getgrnam`.

Returns
`int` | The integer GID corresponding to the given string.

Raises
`ValueError` | If the group name is supplied and `grp` is not available.

def initgroups(uid, primaryGid): (source)

Do nothing.

Underlying platform support require to manipulate groups is missing.

def makeStatBar(width, maxPosition, doneChar='=', undoneChar='-', currentChar='>'): (source)

Creates a function that will return a string representing a progress bar.

def mergeFunctionMetadata(f, g): (source)

Overwrite `g`'s name and docstring with values from `f`. Update `g`'s instance dictionary with `f`'s.

Returns
A function that has `g`'s behavior and metadata merged from `f`.

def nameToLabel(mname): (source)

Convert a string like a variable name into a slightly more human-friendly string with spaces and capitalized letters.

Parameters
mname:`str` | The name to convert to a label. This must be a string which could be used as a Python identifier. Strings which do not take this form will result in unpredictable behavior.

Returns
`str` | Undocumented

def padTo(n, seq, default=None): (source)

Pads a sequence out to n elements,

filling in with a default value if it is not long enough.

If the input sequence is longer than n, raises ValueError.

Details, details: This returns a new list; it does not extend the original sequence. The new list contains the values of the original sequence, not copies.

def println(*a): (source)

Undocumented

def raises(exception, f, *args, **kwargs): (source)

Determine whether the given call raises the given exception.

def runAsEffectiveUser(euid, egid, function, *args, **kwargs): (source)

Run the given function wrapped with seteuid/setegid calls.

This will try to minimize the number of seteuid/setegid calls, comparing current and wanted permissions

Parameters
euid:`int` | effective UID used to call the function.
egid:effective GID used to call the function. | `int`
function:any callable | the function run with the specific permission.
*args | arguments passed to `function`
**kwargs | keyword arguments passed to `function`

def runWithWarningsSuppressed(suppressedWarnings, f, *args, **kwargs): (source)

Run `f(*args, **kwargs)`, but with some warnings suppressed.

Unlike `twisted.internet.utils.runWithWarningsSuppressed`, it has no special support for `twisted.internet.defer.Deferred`.

Parameters
suppressedWarnings | A list of arguments to pass to `warnings.filterwarnings`. Must be a sequence of 2-tuples (args, kwargs).
f | A callable.
*args | Arguments for `f`.
**kwargs | Keyword arguments for `f`

Returns
The result of `f(*args, **kwargs)`.

def searchupwards(start, files=[], dirs=[]): (source)

Walk upwards from start, looking for a directory containing all files and directories given as arguments:

    >>> searchupwards('.', ['foo.txt'], ['bar', 'bam'])

If not found, return None

def sibpath(path: `os.PathLike[AnyStr] | AnyStr`, sibling: `os.PathLike[AnyStr] | AnyStr`) -> `AnyStr`: (source)

Return the path to a sibling of a file in the filesystem.

This is useful in conjunction with the special `__file__` attribute that Python provides for modules, so modules can load associated resource files.

def spewer(frame, s, ignored): (source)

A trace function for sys.settrace that prints every function or method call.

def str_xor(s, b): (source)

Undocumented

def switchUID(uid, gid, euid=False): (source)

Attempts to switch the uid/euid and gid/egid for the current process.

If `uid` is the same value as `os.getuid` (or `os.geteuid`), this function will issue a `UserWarning` and not raise an exception.

Parameters
uid:`int` or `None` | the UID (or EUID) to switch the current process to. This parameter will be ignored if the value is `None`.
gid:`int` or `None` | the GID (or EGID) to switch the current process to. This parameter will be ignored if the value is `None`.
euid:`bool` | if True, set only effective user-id rather than real user-id. (This option has no effect unless the process is running as root, in which case it means not to shed all privileges, retaining the option to regain privileges in cases such as spawning processes. Use with caution.)

def uidFromString(uidString): (source)

Convert a user identifier, as a string, into an integer UID.

Parameters
uidString:`str` | A string giving the base-ten representation of a UID or the name of a user which can be converted to a UID via `pwd.getpwnam`.

Returns
`int` | The integer UID corresponding to the given string.

Raises
`ValueError` | If the user name is supplied and `pwd` is not available.

def uniquify(lst): (source)

Make the elements of a list unique by inserting them into a dictionary. This must not change the order of the input lst.

def untilConcludes(f, *a, **kw): (source)

Call `f` with the given arguments, handling `EINTR` by retrying.

Parameters
f | A function to call.
*a | Positional arguments to pass to `f`.
**kw | Keyword arguments to pass to `f`.

Returns
Whatever `f` returns.

Raises
`Exception` | Whatever `f` raises, except for `OSError` with `errno` set to `EINTR`.

def _getpass(prompt): (source)

Helper to turn IOErrors into KeyboardInterrupts.

_T = (source)

Undocumented

Value

    TypeVar('_T')