pytestshellutils.utils package¶

pytestshellutils.utils.resolved_pathlib_path(path: Union[str, pathlib.Path]) → pathlib.Path[source]¶: Return a resolved pathlib.Path.

pytestshellutils.utils.format_callback_to_string(callback: Union[str, Callable[[...], Any]], args: Optional[Tuple[Any, ...]] = None, kwargs: Optional[Dict[str, Any]] = None) → str[source]¶

Convert a callback, its arguments and keyword arguments to a string suitable for logging purposes.

Parameters

callback (Callable,str) – The callback function
args (list,tuple) – The callback arguments
kwargs (dict) – The callback keyword arguments

Return type

str

pytestshellutils.utils.warn_until(version: str, message: str, category: typing.Type[Warning] = <class 'DeprecationWarning'>, stacklevel: typing.Optional[int] = None, _dont_call_warnings: bool = False, _pkg_version_: typing.Optional[str] = None) → None[source]¶

Show a deprecation warning.

Helper function to raise a warning, by default, a DeprecationWarning, until the provided version, after which, a RuntimeError will be raised to remind the developers to remove the warning because the target version has been reached.

Parameters

version – The version string after which the warning becomes a RuntimeError. For example 2.1.
message – The warning message to be displayed.
category – The warning class to be thrown, by default DeprecationWarning
stacklevel – There should be no need to set the value of stacklevel.
_dont_call_warnings – This parameter is used just to get the functionality until the actual error is to be issued. When we’re only after the version checks to raise a RuntimeError.

Submodules¶

pytestshellutils.utils.ports module¶

Ports related utility functions.

pytestshellutils.utils.ports.get_unused_localhost_port(use_cache: bool = False) → int[source]¶

Return a random unused port on localhost.

Keyword Arguments: use_cache (bool) – If use_cache is True, consecutive calls to this function will never return the cached port.

pytestshellutils.utils.ports.get_connectable_ports(ports: Iterable[int]) → Set[int][source]¶

Given a list of ports, returns those that we can connect to.

Parameters: ports (Iterable) – An iterable of ports to try and connect to
Return type: set
Returns: Returns a set of the ports where connection was successful

pytestshellutils.utils.processes module¶

Process related utilities.

class pytestshellutils.utils.processes.MatchString[source]¶

Bases: str

Simple subclass around str which provides a .matcher property.

This .matcher property is an instance of LineMatcher

property matcher: _pytest.pytester.LineMatcher¶: Return an instance of LineMatcher.

pytestshellutils.utils.processes.convert_string_to_match_string(value: Optional[str]) → Optional[pytestshellutils.utils.processes.MatchString][source]¶: Convert strings into MatchString instances.

class pytestshellutils.utils.processes.ProcessResult(*, returncode: int, stdout: Optional[str], stderr: Optional[str], cmdline: Optional[List[str]] = None, data_key: Optional[str] = None, data: Optional[Dict[Any, Any]] = NOTHING)[source]¶

Bases: object

Wrapper class around a subprocess result.

This class serves the purpose of having a common result class which will hold the resulting data from a subprocess command.

Keyword Arguments

returncode (int) – The returncode returned by the process
stdout (str) – The stdout returned by the process
stderr (str) – The stderr returned by the process
cmdline (list,tuple) – The command line used to start the process
data (dict) – The data returned by parsing stdout, when possible.
data_key (str) – When stdout can be parsed as JSON, sometimes there’s a top level key which is not that interesting. By using data_key, we define that we’re actually only interested on the data structure which is keyed by data_key.

Note

Cast ProcessResult to a string to pretty-print it.

returncode: int¶

stdout: str¶

stderr: str¶

cmdline: Optional[List[str]]¶

data_key: Optional[str]¶

data: Optional[Dict[Any, Any]]¶

property exitcode: int¶

Return the process returncode.

This property is deprecated and should not be used. It only exists to support projects that are migrating from pytest-salt-factories versions. Use .returncode instead.

property json: Optional[Dict[Any, Any]]¶

Return the process output parsed as JSON, if possible.

This property is deprecated and should not be used. It only exists to support projects that are migrating from pytest-salt-factories versions. Use .data instead.

__str__() → str[source]¶: String representation of the class.

pytestshellutils.utils.processes.collect_child_processes(pid: int) → List[psutil.Process][source]¶

Try to collect any started child processes of the provided pid.

Parameters: pid (int) – The PID of the process

pytestshellutils.utils.processes.terminate_process_list(process_list: List[psutil.Process], kill: bool = False, slow_stop: bool = False) → None[source]¶

Terminate a list of processes.

Parameters

process_list (Iterable) – An iterable of psutil.Process instances to terminate

Keyword Arguments

kill (bool) – Kill the process instead of terminating it.
slow_stop (bool) – First try to terminate each process in the list, and if termination was not successful, kill it.

pytestshellutils.utils.processes.terminate_process(pid: Optional[int] = None, process: Optional[psutil.Process] = None, children: Optional[List[psutil.Process]] = None, kill_children: Optional[bool] = None, slow_stop: bool = False) → None[source]¶

Try to terminate/kill the started process.

Keyword Arguments

pid (int) – The PID of the process
process (Process) – An instance of psutil.Process
children (Iterable) – An iterable of psutil.Process instances, children to the process being terminated
kill_children (bool) – Also try to terminate/kill child processes
slow_stop (bool) – First try to terminate each process in the list, and if termination was not successful, kill it.

pytestshellutils.utils.socket module¶

Namespace the standard library socket module.

This module’s sole purpose is to have the standard library socket module functions under a different namespace to be used in pytest-shell-utilities so that projects using it, which need to mock socket functions, don’t influence the pytest-shell-utilities run time behavior.

pytestshellutils.utils.time module¶

Namespace the standard library time module.

This module’s sole purpose is to have the standard library time module functions under a different namespace to be used in pytest-shell-utilities so that projects using it, which need to mock time functions, don’t influence the pytest-shell-utilities run time behavior.