mock.os.process
===============

.. py:module:: mock.os.process

.. autoapi-nested-parse::

   Submodule that mocks Run.



Attributes
----------

.. autoapisummary::

   mock.os.process.P


Exceptions
----------

.. autoapisummary::

   mock.os.process.MockRunError
   mock.os.process.UnexpectedCommandError


Classes
-------

.. autoapisummary::

   mock.os.process.ArgumentChecker
   mock.os.process.GlobChecker
   mock.os.process.SideEffect
   mock.os.process.CommandResult
   mock.os.process.MockRun


Functions
---------

.. autoapisummary::

   mock.os.process.mock_run


Module Contents
---------------

.. py:data:: P

.. py:exception:: MockRunError

   Bases: :py:obj:`Exception`


   Error raised by mock_run.


.. py:exception:: UnexpectedCommandError

   Bases: :py:obj:`MockRunError`


   Error raised when MockRun receives an unexpected command.


.. py:function:: mock_run(config: MockRunConfig | None = None) -> collections.abc.Iterator[MockRun]

   Mock e3.os.process.Run as a context or decorator.

   :param config: config for the mock
   :return: new MockRun instance


.. py:class:: ArgumentChecker

   Bases: :py:obj:`Protocol`


   Argument checker.


   .. py:method:: check(arg: str) -> bool

      Check an argument.

      :param arg: the argument
      :return: if the argument is valid



   .. py:method:: __repr__() -> str

      Return a textual representation of the expected argument.



.. py:class:: GlobChecker(pattern: str)

   Bases: :py:obj:`ArgumentChecker`


   Check an argument against a glob.


   .. py:attribute:: pattern


   .. py:method:: check(arg: str) -> bool

      See ArgumentChecker.



   .. py:method:: __repr__() -> str

      See ArgumentChecker.



.. py:class:: SideEffect

   Bases: :py:obj:`Protocol`


   Function to be called when a mocked command is called.


   .. py:method:: __call__(result: CommandResult, cmd: list[str], *args: Any, **kwargs: Any) -> None

      Run when the mocked command is called.

      :param result: the mocked command
      :param cmd: actual arguments of the command
      :param args: additional arguments for Run
      :param kwargs: additional keyword arguments for Run



.. py:class:: CommandResult(cmd: list[str | ArgumentChecker], status: int | None = None, raw_out: bytes = b'', raw_err: bytes = b'', side_effect: SideEffect | None = None)

   Result of a command.

   When a command is supposed to be run, the actual status code and
   logs are taken from this object.


   .. py:attribute:: cmd


   .. py:attribute:: status


   .. py:attribute:: raw_out
      :value: b''



   .. py:attribute:: raw_err
      :value: b''



   .. py:attribute:: side_effect
      :value: None



   .. py:method:: check(cmd: list[str]) -> None

      Check that cmd matches the expected arguments.

      :param cmd: actual command



   .. py:method:: __call__(cmd: list[str], *args: Any, **kwargs: Any) -> None

      Allow to run code to emulate the command.

      This function is called when a command is supposed to be run by Run. It
      takes the same arguments as Run.__init__.

      :param cmd: actual arguments of the command
      :param args: additional arguments for Run
      :param kwargs: additional keyword arguments for Run



.. py:class:: MockRun(config: MockRunConfig | None = None)

   Bases: :py:obj:`e3.os.process.Run`


   Mock e3.os.process.Run.


   .. py:attribute:: config
      :type:  MockRunConfig


   .. py:attribute:: call_count
      :value: 0



   .. py:property:: all_called
      :type: bool


      Check all expected commands have been run.



   .. py:method:: add_result(result: CommandResult | collections.abc.Iterable[CommandResult]) -> None

      Queue one or multiple command results.

      :param result: new command results



   .. py:method:: __call__(cmds: e3.os.process.AnyCmdLine, *args: Any, **kwargs: Any) -> e3.os.process.Run

      Emulate how e3.os.process.Run.__init__ works.

      Once e3.os.process.Run is patched, this function will be called instead.

      :param cmds: command line
      :param args: unhandled arguments
      :param kwargs: unhandled keyword arguments



