Go to the latest version of this document.
search in docstrings

Search bar offers the following options:

- Term presence. The below example searches for documents that must contain “foo”, might contain “bar” and must not contain “baz”: `+foo bar -baz`
- Wildcards. The below example searches for documents with words beginning with “foo”: `foo*`
- Search in specific fields. The following search matches all objects in "twisted.mail" that matches “search”: `+qname:twisted.mail.* +search`

  Possible fields: 'name', 'qname' (fully qualified name), 'docstring', and 'kind'. Last two fields are only applicable if "search in docstrings" is enabled.

- Fuzzy matches. The following search matches all documents that have a word within 1 edit distance of “foo”: `foo~1`

Results provided by Lunr.js

# ``twisted`.`trial`.`util``

module documentation
(source)

A collection of utility functions and classes, used internally by Trial.

This code is for Trial's internal use. Do NOT use this code if you are writing tests. It is subject to change at the Trial maintainer's whim. There is nothing here in this module for you to use unless you are maintaining Trial.

Any non-Trial Twisted code that uses this module will be shot.

Maintainer: Jonathan Lange

Exception | `DirtyReactorAggregateError` | Passed to `twisted.trial.itrial.IReporter.addError` when the reactor is left in an unclean state after a test.
Function | `acquireAttribute` | Go through the list 'objects' sequentially until we find one which has attribute 'attr', then return the value of that attribute. If not found, return 'default' if set, otherwise, raise AttributeError.
Function | `excInfoOrFailureToExcInfo` | Coerce a Failure to an _exc_info, if err is a Failure.
Function | `openTestLog` | Open the given path such that test log messages can be written to it.
Function | `profiled` | Undocumented
Function | `suppress` | Sets up the .suppress tuple properly, pass options to this method as you would the stdlib warnings.filterwarnings()
Constant | `DEFAULT_TIMEOUT` | Undocumented
Constant | `DEFAULT_TIMEOUT_DURATION` | The default timeout which will be applied to asynchronous (ie, Deferred-returning) test methods, in seconds.
Class | `_Janitor` | The guy that cleans up after you.
Exception | `_NoTrialMarker` | No trial marker file could be found.
Exception | `_WorkingDirectoryBusy` | A working directory was specified to the runner, but another test run is currently using that directory.
Function | `_listToPhrase` | Produce a string containing each thing in `things`, separated by a `delimiter`, with the last couple being separated by `finalDelimiter`
Function | `_removeSafely` | Safely remove a path, recursively.
Function | `_unusedTestDirectory` | Find an unused directory named similarly to `base`.
Constant | `_DEFAULT` | Undocumented
Constant | `_P` | Undocumented
Type Variable | `_T` | Undocumented

def acquireAttribute(objects, attr, default=_DEFAULT): (source)

Go through the list 'objects' sequentially until we find one which has attribute 'attr', then return the value of that attribute. If not found, return 'default' if set, otherwise, raise AttributeError.

def excInfoOrFailureToExcInfo(err): (source)

Coerce a Failure to an _exc_info, if err is a Failure.

Parameters
err | Either a tuple such as returned by `sys.exc_info` or a `Failure` object.
Returns
A tuple like the one returned by `sys.exc_info`. e.g. `exception_type, exception_object, traceback_object`.

def openTestLog(path: `FilePath[Any]`) -> `TextIO`: (source)

Open the given path such that test log messages can be written to it.

def profiled(f: `Callable[_P, _T]`, outputFile: `str`) -> `Callable[_P, _T]`: (source)

Undocumented

def suppress(action='ignore', **kwarg): (source)

Sets up the .suppress tuple properly, pass options to this method as you would the stdlib warnings.filterwarnings()

So, to use this with a .suppress magic attribute you would do the following:

    >>> from twisted.trial import unittest, util
    >>> import warnings
    >>>
    >>> class TestFoo(unittest.TestCase):
    ...     def testFooBar(self):
    ...         warnings.warn("i am deprecated", DeprecationWarning)
    ...     testFooBar.suppress = [util.suppress(message='i am deprecated')]
    ...
    >>>

Note that as with the todo and timeout attributes: the module level attribute acts as a default for the class attribute which acts as a default for the method attribute. The suppress attribute can be overridden at any level by specifying `.suppress = []`

DEFAULT_TIMEOUT = (source)

Undocumented

Value

    object()

DEFAULT_TIMEOUT_DURATION: `float` = (source)

The default timeout which will be applied to asynchronous (ie, Deferred-returning) test methods, in seconds.

Value

    120.0

def _listToPhrase(things, finalDelimiter, delimiter=', '): (source)

Produce a string containing each thing in `things`, separated by a `delimiter`, with the last couple being separated by `finalDelimiter`

Parameters
things:`list` or `tuple` | The elements of the resulting phrase
finalDelimiter:`str` | What to put between the last two things (typically 'and' or 'or')
delimiter:`str` | The separator to use between each thing, not including the last two. Should typically include a trailing space.
Returns
`str` | The resulting phrase

def _removeSafely(path): (source)

Safely remove a path, recursively.

If `path` does not contain a node named `_trial_marker`, a `_NoTrialMarker` exception is raised and the path is not removed.

def _unusedTestDirectory(base): (source)

Find an unused directory named similarly to `base`.

Once a directory is found, it will be locked and a marker dropped into it to identify it as a trial temporary directory.

Parameters
base:`FilePath` | A template path for the discovery process. If this path exactly cannot be used, a path which varies only in a suffix of the basename will be used instead.
Returns
A two-tuple. The first element is a `FilePath` representing the directory which was found and created. The second element is a locked `FilesystemLock`. Another call to `_unusedTestDirectory` will not be able to reused the same name until the lock is released, either explicitly or by this process exiting.

_DEFAULT = (source)

Undocumented

Value

    object()

_P = (source)

Undocumented

Value

    ParamSpec('_P')

_T = (source)

Undocumented

Value

    TypeVar('_T')