pytestshellutils package¶
Subpackages¶
Submodules¶
pytestshellutils.customtypes module¶
Custom Types.
- class pytestshellutils.customtypes.GenericCallback(*args, **kwargs)[source]¶
Bases:
Protocol
Generic callback function.
- class pytestshellutils.customtypes.DaemonCallback(*args, **kwargs)[source]¶
Bases:
Protocol
Daemon callback function.
pytestshellutils.exceptions module¶
Pytest Shell Utilities related exceptions.
- exception pytestshellutils.exceptions.ShellUtilsException[source]¶
Bases:
Exception
Base pytest shell utilities exception.
- exception pytestshellutils.exceptions.CallbackException[source]¶
Bases:
pytestshellutils.exceptions.ShellUtilsException
Exception raised during a before/after start/stop daemon callback.
- exception pytestshellutils.exceptions.ProcessFailed(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.ShellUtilsException
Exception raised when a sub-process fails.
- Parameters
message (str) – The exception message
- Keyword Arguments
process_result – ProcessResult: The
ProcessResult
instance when the exception occurred
- exception pytestshellutils.exceptions.FactoryFailure(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.ProcessFailed
Exception raised when a sub-process fails on one of the factories.
- exception pytestshellutils.exceptions.FactoryNotStarted(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.FactoryFailure
Exception raised when a factory failed to start.
Please look at
FactoryFailure
for the supported keyword arguments documentation.
- exception pytestshellutils.exceptions.FactoryNotRunning(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.FactoryFailure
Exception raised when trying to use a factory’s .stopped context manager and the factory is not running.
Please look at
FactoryFailure
for the supported keyword arguments documentation.
- exception pytestshellutils.exceptions.ProcessNotStarted(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.FactoryFailure
Exception raised when a process failed to start.
Please look at
FactoryFailure
for the supported keywords. arguments documentation.
- exception pytestshellutils.exceptions.FactoryTimeout(message: str, process_result: Optional[pytestshellutils.utils.processes.ProcessResult] = None)[source]¶
Bases:
pytestshellutils.exceptions.FactoryNotStarted
Exception raised when a process timed-out.
Please look at
FactoryFailure
for the supported keywords. arguments documentation.
pytestshellutils.plugin module¶
Pytest shell utilities plugin.
- pytestshellutils.plugin.shell() pytestshellutils.shell.Subprocess [source]¶
Shell fixture.
pytestshellutils.shell module¶
Shelling class implementations.
- class pytestshellutils.shell.BaseFactory(*, cwd: Union[str, pathlib.Path] = NOTHING, environ: pytestshellutils.customtypes.EnvironDict = NOTHING)[source]¶
Bases:
object
Base factory class.
- Keyword Arguments
cwd (pathlib.Path) – The path to the desired working directory
environ (dict) – A dictionary of
key
,value
pairs to add to the environment.
- cwd: pathlib.Path¶
- class pytestshellutils.shell.SubprocessImpl(*, factory: Union[Factory, Subprocess, ScriptSubprocess])[source]¶
Bases:
object
Subprocess interaction implementation.
- Keyword Arguments
factory (Subprocess) – The factory instance, either
Subprocess
or a sub-class of it.
- factory: Union[pytestshellutils.shell.Factory, pytestshellutils.shell.Subprocess, pytestshellutils.shell.ScriptSubprocess]¶
- cmdline(*args: str, **kwargs: Any) List[str] [source]¶
Construct a list of arguments to use when starting the subprocess.
- Parameters
args (str) – Additional arguments to use when starting the subprocess
By default, this method will just call it’s factory’s
cmdline()
method, but can be overridden.
- init_terminal(cmdline: List[str], env: Optional[pytestshellutils.customtypes.EnvironDict] = None) subprocess.Popen[Any] [source]¶
Instantiate a terminal with the passed command line(
cmdline
) and return it.Additionally, it sets a reference to it in
self._terminal
and also collects an initial listing of child processes which will be used when terminating the terminal
- is_running() bool [source]¶
Returns true if the sub-process is alive.
- Returns
Returns true if the sub-process is alive
- Return type
- terminate() pytestshellutils.utils.processes.ProcessResult [source]¶
Terminate the started subprocess.
- Return type
- run(*args: str, env: Optional[pytestshellutils.customtypes.EnvironDict] = None, **kwargs: Any) subprocess.Popen[Any] [source]¶
Run the given command synchronously.
- class pytestshellutils.shell.Factory(*, cwd: Union[str, pathlib.Path] = NOTHING, environ: pytestshellutils.customtypes.EnvironDict = NOTHING, slow_stop: bool = True, system_encoding: str = NOTHING, timeout: Union[int, float] = NOTHING)[source]¶
Bases:
pytestshellutils.shell.BaseFactory
Base shell factory class.
- Keyword Arguments
slow_stop (bool) – Whether to terminate the processes by sending a
SIGTERM
signal or by callingterminate()
on the sub-process. When code coverage is enabled, one will want slow_stop set to True so that coverage data can be written down to disk.system_encoding (str) – The system encoding to use when decoding the subprocess output. Defaults to “utf-8”.
timeout (int,float) – The default maximum amount of seconds that a script should run. This value can be overridden when calling
run()
through the_timeout
keyword argument, and, in that case, the timeout value applied would be that of_timeout
instead ofself.timeout
.
- terminate() pytestshellutils.utils.processes.ProcessResult [source]¶
Terminate the started subprocess.
- __ne__(other)¶
Method generated by attrs for class Factory.
- class pytestshellutils.shell.Subprocess(*, cwd: Union[str, pathlib.Path] = NOTHING, environ: pytestshellutils.customtypes.EnvironDict = NOTHING, slow_stop: bool = True, system_encoding: str = NOTHING, timeout: Union[int, float] = NOTHING)[source]¶
Bases:
pytestshellutils.shell.Factory
Base shell factory class.
- class pytestshellutils.shell.ScriptSubprocess(*, cwd: Union[str, pathlib.Path] = NOTHING, environ: pytestshellutils.customtypes.EnvironDict = NOTHING, slow_stop: bool = True, system_encoding: str = NOTHING, timeout: Union[int, float] = NOTHING, script_name: str, base_script_args: List[str] = NOTHING)[source]¶
Bases:
pytestshellutils.shell.Subprocess
Base CLI script/binary class.
- Keyword Arguments
script_name (str) – This is the string containing the name of the binary to call on the subprocess, either the full path to it, or the basename. In case of the basename, the directory containing the basename must be in your
$PATH
variable.base_script_args (list,tuple) – An list or tuple iterable of the base arguments to use when building the command line to launch the process
Please look at
Factory
for the additional supported keyword arguments documentation.
- class pytestshellutils.shell.StartDaemonCallArguments(*, args: Tuple[str, ...], kwargs: Dict[str, Any])[source]¶
Bases:
object
This class holds the arguments and keyword arguments used to start a daemon.
It’s used when restarting the daemon so that the same call is used.
- Keyword Arguments
- class pytestshellutils.shell.DaemonImpl(*, factory: Daemon, before_start_callbacks: List[pytestshellutils.customtypes.Callback] = NOTHING, after_start_callbacks: List[pytestshellutils.customtypes.Callback] = NOTHING, before_terminate_callbacks: List[pytestshellutils.customtypes.Callback] = NOTHING, after_terminate_callbacks: List[pytestshellutils.customtypes.Callback] = NOTHING)[source]¶
Bases:
pytestshellutils.shell.SubprocessImpl
Daemon subprocess interaction implementation.
Please look at
SubprocessImpl
for the additional supported keyword arguments documentation.- factory: pytestshellutils.shell.Daemon¶
- before_start(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run before the daemon starts.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- after_start(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run after the daemon starts.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- before_terminate(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run before the daemon terminates.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- after_terminate(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run after the daemon terminates.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- start(*extra_cli_arguments: str, max_start_attempts: Optional[int] = None, start_timeout: Optional[Union[int, float]] = None) bool [source]¶
Start the daemon.
- Keyword Arguments
extra_cli_arguments (tuple) – Extra arguments to pass to the CLI that starts the daemon
max_start_attempts (int) – Maximum number of attempts to try and start the daemon in case of failures
start_timeout (int,float) – The maximum number of seconds to wait before considering that the daemon did not start
- terminate() pytestshellutils.utils.processes.ProcessResult [source]¶
Terminate the daemon.
- get_start_arguments() pytestshellutils.shell.StartDaemonCallArguments [source]¶
Return the arguments and keyword arguments used when starting the daemon.
- Return type
- class pytestshellutils.shell.Daemon(*, cwd: Union[str, pathlib.Path] = NOTHING, environ: pytestshellutils.customtypes.EnvironDict = NOTHING, slow_stop: bool = True, system_encoding: str = NOTHING, timeout: Union[int, float] = NOTHING, script_name: str, base_script_args: List[str] = NOTHING, check_ports: List[int] = NOTHING, stats_processes: StatsProcesses = None, start_timeout: Union[int, float], max_start_attempts: int = 3, extra_cli_arguments_after_first_start_failure: List[str] = NOTHING)[source]¶
Bases:
pytestshellutils.shell.ScriptSubprocess
Base daemon factory.
- Keyword Arguments
check_ports (list) – List of ports to try and connect to while confirming that the daemon is up and running
extra_cli_arguments_after_first_start_failure (tuple,) – Extra arguments to pass to the CLI that starts the daemon after the first failure
max_start_attempts (int) – Maximum number of attempts to try and start the daemon in case of failures
start_timeout (int) – The maximum number of seconds to wait before considering that the daemon did not start
Please look at
Subprocess
for the additional supported keyword arguments documentation.- stats_processes: StatsProcesses¶
- before_start(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run before the daemon starts.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- after_start(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run after the daemon starts.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- before_terminate(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run before the daemon terminates.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- after_terminate(callback: Callable[[], None], *args: Any, **kwargs: Any) None [source]¶
Register a function callback to run after the daemon terminates.
- Parameters
callback (Callable) – The function to call back
- Keyword Arguments
args – The arguments to pass to the callback
kwargs – The keyword arguments to pass to the callback
- get_check_ports() List[int] [source]¶
Return a list of ports to check against to ensure the daemon is running.
- start(*extra_cli_arguments: str, max_start_attempts: Optional[int] = None, start_timeout: Optional[Union[int, float]] = None) bool [source]¶
Start the daemon.
- started(*extra_cli_arguments: str, max_start_attempts: Optional[int] = None, start_timeout: Optional[Union[int, float]] = None) pytestshellutils.shell.Daemon [source]¶
Start the daemon and return it’s instance so it can be used as a context manager.
- stopped(before_stop_callback: Optional[Callable[[pytestshellutils.shell.Daemon], None]] = None, after_stop_callback: Optional[Callable[[pytestshellutils.shell.Daemon], None]] = None, before_start_callback: Optional[Callable[[pytestshellutils.shell.Daemon], None]] = None, after_start_callback: Optional[Callable[[pytestshellutils.shell.Daemon], None]] = None) Generator[pytestshellutils.shell.Daemon, None, None] [source]¶
Stop the daemon and return it’s instance so it can be used as a context manager.
- Keyword Arguments
before_stop_callback (Callable) – A callable to run before stopping the daemon. The callback must accept one argument, the daemon instance.
after_stop_callback (Callable) – A callable to run after stopping the daemon. The callback must accept one argument, the daemon instance.
before_start_callback (Callable) – A callable to run before starting the daemon. The callback must accept one argument, the daemon instance.
after_start_callback (Callable) – A callable to run after starting the daemon. The callback must accept one argument, the daemon instance.
This context manager will stop the factory while the context is in place, it re-starts it once out of context.
For example:
assert factory.is_running() is True with factory.stopped(): assert factory.is_running() is False assert factory.is_running() is True
- run_start_checks(started_at: float, timeout_at: float) bool [source]¶
Run checks to confirm that the daemon has started.
- __enter__() pytestshellutils.shell.Daemon [source]¶
Use class as a context manager.