mirakuru 3.0.3

SimpleExecutor

The simplest executor implementation. It simply starts the process passed to constructor, and reports it as running.

from mirakuru import SimpleExecutor

process = SimpleExecutor('my_special_process')
process.start()

# Here you can do your stuff, e.g. communicate with the started process

process.stop()

OutputExecutor

OutputExecutor starts a process and monitors its output for a specific text marker (banner). The process is not reported as started until this marker appears in the output.

from mirakuru import OutputExecutor

process = OutputExecutor('my_special_process', banner='processed!')
process.start()

# Here you can do your stuff, e.g. communicate with the started process

process.stop()

What happens during start here, is that the executor constantly checks output produced by started process, and looks for the banner part occurring within the output. Once the output is identified, as in example processed! is found in output. It is considered as started, and executor releases your script from wait to work.

TCPExecutor

TCPExecutor should be used to start processes that communicate over TCP connections. This executor tries to connect to the process on the specified host and port to check if it started accepting connections. Once it successfully connects, the process is reported as started and control returns to your code.

from mirakuru import TCPExecutor

process = TCPExecutor('my_special_process', host='localhost', port=1234)
process.start()

# Here you can do your stuff, e.g. communicate with the started process

process.stop()

HTTPExecutor

HTTPExecutor is designed for starting web applications and HTTP services. In addition to the command, you need to pass a URL that will be used to check if the service is ready. By default, it makes a HEAD request to this URL. Once the request succeeds, the executor reports the process as started and control returns to your code.

from mirakuru import HTTPExecutor

process = HTTPExecutor('my_special_process', url='http://localhost:6543/status')
process.start()

# Here you can do your stuff, e.g. communicate with the started process

process.stop()

This executor, however, apart from HEAD request, also inherits TCPExecutor, so it’ll try to connect to process over TCP first, to determine, if it can try to make a HEAD request already.

By default HTTPExecutor waits until its subprocess responds with 2XX HTTP status code. If you consider other codes as valid you need to specify them in ‘status’ argument.

from mirakuru import HTTPExecutor

process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)')
process.start()

The “status” argument can be a single code integer like 200, 404, 500 or a regular expression string - ‘^(2|4)00$’, ‘2dd’, ‘d{3}’, etc.

There’s also a possibility to change the request method used to perform request to the server. By default it’s HEAD, but GET, POST or other are also possible.

from mirakuru import HTTPExecutor

process = HTTPExecutor('my_special_process', url='http://localhost:6543/status', status='(200|404)', method='GET')
process.start()

PidExecutor

Is an executor that starts the given process, and then waits for a given file to be found before it gives back control. An example use for this class is writing integration tests for processes that notify their running by creating a .pid file.

from mirakuru import PidExecutor

process = PidExecutor('my_special_process', filename='/var/msp/my_special_process.pid')
process.start()

# Here you can do your stuff, e.g. communicate with the started process

process.stop()

from mirakuru import HTTPExecutor
from http.client import HTTPConnection, OK


def test_it_works():
    # The ``./http_server`` here launches some HTTP server on the 6543 port,
    # but naturally it is not immediate and takes a non-deterministic time:
    executor = HTTPExecutor("./http_server", url="http://127.0.0.1:6543/")

    # Start the server and wait for it to run (blocking):
    executor.start()
    # Here the server should be running!
    conn = HTTPConnection("127.0.0.1", 6543)
    conn.request("GET", "/")
    assert conn.getresponse().status is OK
    executor.stop()

A command by which executor spawns a process can be defined by either string or list.

# command as string
TCPExecutor('python -m smtpd -n -c DebuggingServer localhost:1025', host='localhost', port=1025)
# command as list
TCPExecutor(
    ['python', '-m', 'smtpd', '-n', '-c', 'DebuggingServer', 'localhost:1025'],
    host='localhost', port=1025
)

Starting

Mirakuru executors can also work as a context managers.

from mirakuru import HTTPExecutor

with HTTPExecutor('my_special_process', url='http://localhost:6543/status') as process:

    # Here you can do your stuff, e.g. communicate with the started process
    assert process.running() is True

assert process.running() is False

Defined process starts upon entering context, and exit upon exiting it.

Stopping

Mirakuru also allows to stop process for given context. To do this, simply use built-in stopped context manager.

from mirakuru import HTTPExecutor

process = HTTPExecutor('my_special_process', url='http://localhost:6543/status').start()

# Here you can do your stuff, e.g. communicate with the started process

with process.stopped():

    # Here you will not be able to communicate with the process as it is killed here
    assert process.running() is False

assert process.running() is True

Defined process stops upon entering context, and starts upon exiting it.

Methods chaining

Mirakuru encourages methods chaining so you can inline some operations, e.g.:

from mirakuru import SimpleExecutor

command_stdout = SimpleExecutor('my_special_process').start().stop().output