pytestshellutils.utils package#

pytestshellutils.utils.resolved_pathlib_path(path: str | Path) → Path[source]#

Return a resolved pathlib.Path.

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

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

Parameters:

callback – The callback function

Keyword Arguments:

  • args – The callback arguments

  • kwargs – The callback keyword arguments

Returns:

The formatted callback string

Return type:

str

pytestshellutils.utils.warn_until(version: str, message: str, category: ~typing.Type[Warning] = <class 'DeprecationWarning'>, stacklevel: int | None = None, _dont_call_warnings: bool = False, _pkg_version_: str | None = 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.

Keyword Arguments:

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

Returns:

Nothing.

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 – 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 – An iterable of ports to try and connect to

Returns:

Returns a set of the ports where connection was successful

Return type:

set

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: LineMatcher#

Return an instance of LineMatcher.

pytestshellutils.utils.processes.convert_string_to_match_string(value: str | None) → MatchString | None[source]#

Convert strings into MatchString instances.

class pytestshellutils.utils.processes.ProcessResult(*, returncode: int, stdout: str | None, stderr: str | None, cmdline: List[str] | None = None, data_key: str | None = None, data: Dict[Any, Any] | None = _Nothing.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 – The returncode returned by the process

  • stdout – The stdout returned by the process

  • stderr – The stderr returned by the process

  • cmdline – The command line used to start the process

  • data – The data returned by parsing stdout, when possible.

  • data_key – 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: MatchString#
stderr: MatchString#
cmdline: List[str] | None#
data_key: str | None#
data: Dict[Any, Any] | None#
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: Dict[Any, Any] | None#

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[Process][source]#

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

Parameters:

pid – The PID of the process

Returns:

List of child processes

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

Terminate a list of processes.

Parameters:

process_list – An iterable of psutil.Process instances to terminate

Keyword Arguments:

  • kill – Kill the process instead of terminating it.

  • slow_stop – First try to terminate each process in the list, and if termination was not successful, kill it.

Returns:

Nothing.

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

Try to terminate/kill the started process.

Keyword Arguments:

  • pid – The PID of the process

  • process – An instance of psutil.Process

  • children – An iterable of psutil.Process instances, children to the process being terminated

  • kill_children – Also try to terminate/kill child processes

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