Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# pytestshellutils.utils package

pytestshellutils.utils.resolved_pathlib_path(path: str | Path) → Path

  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

  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

  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

  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]

  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

  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

  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)

  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

    String representation of the class.

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

  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

  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

  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.