Sessions

class minke.sessions.Session(con, db, minkeobj=None)

Base-class for all session-classes.

All session-classes must inherit from Session. By defining a subclass of Session the subclass will be implicitly registered as session-class and also a run-permission will be created for it. To prevent this behavior use an abstract session by setting abstract to True.

Each session will be instantiated with a fabric-connection and an object of MinkeSession. The connection-object provides the remote-access, while the minkesession is the database- representation of a specific session running for a specific minkemodel-object.

For a session-class to be useful you at least has to define the process()-method and add one or more MinkeModel to work_on-attribute.

abstract = True

An abstract session-class won’t be registered itself. This is useful if your session-class should be a base-class for other sessions.

Abstract session-classes can be registered manually by calling its classmethod register():

MySession.register()

This won’t add a run-permission-lookup-string to permissions. To do so use the classmethod SessionRegistration.add_permission():

MySession.add_permission()
verbose_name = None

Display-name for sessions.

group = None

Group-name used as optgroup-tag in the select-widget. Best practice to group sessions is to use a SessionGroup.

work_on = ()

Tuple of minke-models. Models the session can be used with.

permissions = ()

Tuple of permission-strings. To be able to run a session a user must have all the permissions listed. The strings should have the following format: “<app-label>.<permission’s-codename>.

auto_permission = True

If True a lookup-string for a session-specific run-permission will be automatically added to permissions.

Note

To avoid database-access on module-level we won’t create the permission itself. Once you setup your sessions you could create run-permissions for all sessions using the api-command:

$ ./manage.py minkeadm --create-permissions
form = None

An optional form that will be rendered before the session will be processed. The form-data will be accessible within the session as the data-property. Use it if the session’s processing depends on additional user-input-data.

Instead of setting the form-attribute you can also directly overwrite get_form().

confirm = False

If confirm is true, the admin-site asks for a user-confirmation before processing a session, which also allows to review the objects the session was revoked with.

invoke_config = {}

Session-specific fabric- and invoke-configuration-parameters which will be used to initialize a fabric-connection. The keys must be formatted in a way that is accepted by load_snakeconfig().

See also the documentation for the configuration of fabric and invoke.

parrallel_per_host = False

Allow parrallel processing of multiple celery-tasks on a single host. If multiple minke-objects are associated with the same host all tasks running on them would be processed in a serial manner by default. This is to protect the ressources of the host-system. If you want to allow parrallel processing of multiple celery-tasks on a single host set parrallel_per_host to True.

Note

To perform parrallel task-execution on a single host we make use of celery’s chords-primitive, which needs a functioning result-backend to be configured. Please see the celery-documentation for more details.

classmethod get_form()

Return form by default.

Overwrite this method if you need to setup your form-class dynamically.

property c

Refers to the fabric.connection.Connection-object the session was initialized with.

property minkeobj

Refers to models.MinkeSession.minkeobj.

property status

Refers to models.MinkeSession.session_status.

property data

Refers to models.MinkeSession.session_data. This model-field holds all the data that comes from form.

stop(*arg, **kwargs)

Interrupt the session’s processing.

This method could be called twice. The first time it will initiate a soft interruption which means a current remote-process won’t be interrupted. The session will be stopped subsequently. If it is called meanwhile a second time, the session will be killed immediately.

Note

It seems that there is no chance to interrupt a shell-process started by fabric if no pty is in use. fabric.runners.Remote.send_interrupt says:

... in v1, we just reraised the KeyboardInterrupt unless a PTY was
present; this seems to have been because without a PTY, the
below escape sequence is ignored, so all we can do is immediately
terminate on our end...

Thus killing a session makes most sense if it has the run.pty-config in use. Otherwise you just will be disconnected from the remote-process.

process()

Real work is done here…

This is the place for your own session-code.

add_msg(msg, level=None)

Add a message.

Parameters

  • msg –

    You could either pass an instance of any message-class, or any type the different message-classes are initiated with:

    • a string for a PreMessage

    • a tuple or list for a TableMessage

    • an object of Result for a ExecutionMessage

  • level (string or bool (optional)) – This could be one of ‘info’, ‘warning’ or ‘error’. If you pass a bool True will be ‘info’ and False will be ‘error’.

set_status(status, update=True)

Set session-status. Pass a valid session-status or a bool.

Parameters

  • status (string or bool) – Valid status as string or True for ‘success’ and False for ‘error’.

  • update (bool (optional)) – If True the session-status could only be raised. Lower values as current will be ignored.

format_cmd(cmd)

Use the data and the fields of the minkeobj as parameters for format() to prepare the given command.

Parameters

cmd (string) – a format-string

Returns

The formatted command.

Return type

string

run(cmd, **invoke_params)

Run a command.

Basically call run() on the Connection-object with the given command and invoke-parameters.

Additionally save the Result-object as an models.CommandResult-object.

Parameters

  • cmd (string) – The shell-command to be run.

  • (optional) (**invoke_params) – Parameters that will be passed to run()

Returns

Return type

object of models.CommandResult

frun(cmd, **invoke_params)

Same as run(), but use format_cmd() to prepare the command-string.

xrun(cmd, **invoke_params)

Same as frun(), but also add a ExecutionMessage and update the session-status.

update_field(field, cmd, regex=None, **invoke_params)

Running a command and update a field of minkeobj.

Assign either result.stdout or if available the first matched regex-group. If result.failed is True or result.stdout is empty or the given regex does not match, the field is updated with None. In this case an error-message will be added.

Parameters

  • field (string) – Name of the field that should be updated.

  • cmd (string) – The shell-command to be run.

  • regex (string (optional)) – A regex-pattern the CommandResult will be initialized with.

  • (optional) (**invoke_params) – Parameters that will be passed to run()

Returns

False if the field was updated with None. True otherwise.

Return type

bool

Raises

AttributeError – If the given field does not exists on minkeobj.

class minke.sessions.SingleCommandSession(con, db, minkeobj=None)

An abstract Session-class to execute a single command.

If you want your session to execute a single command simply create a subclass of SingleCommandSession and overwrite the command-attribute. The command will be executed with xrun().

Example

class MyDrupalModel(models.Model):
    root = models.CharField(max_length=255)

class MySession(SingleCommandSession):
    work_on = (MyDrupalModel,)
    command = 'drush --root={root} cache-clear all'
command = None

Shell-command to be executed.

process()

Real work is done here…

This is the place for your own session-code.

class minke.sessions.CommandFormSession(con, db, minkeobj=None)

Same as class:.SingleCommandSession but rendering a TextField to enter the command.

Example

class MySession(CommandFormSession):
    work_on = (MyModel,)
form

alias of minke.forms.CommandForm

class minke.sessions.CommandChainSession(con, db, minkeobj=None)

An abstract Session-class to execute a sequence of commands.

The commands will be invoked one after another. If one of the commands return with a state defined in break_states no further commands will be executed.

Example

class MySession(CommandChainSession):
    work_on = (MyServer,)
    commands = (
        'a2ensite mysite'
        'apachectl configtest',
        'service apache2 reload')
commands = ()

tuple of shell-commands

break_states = ('error',)

tuple of models.CommandResult.status on which the session will be interrupted

process()

Real work is done here…

This is the place for your own session-code.

class minke.sessions.SessionChain(con, db, minkeobj=None)

An abstract Session-class to execute a sequence of sessions.

If you have some sessions you want to be able to process separately or as a sequence you could make use of a SessionChain.

All sessions have to work with the same minkeobj. If one of the sessions ends up with a status defined in break_states no further sessions will be executed.

Example

class MySession(SessionChain):
    work_on = (MyServer,)
    sessions = (
        UpdateSQLServer,
        RestartSQLServer,
        UpdateApache,
        RestartApache)

Note

It is possible to add abstract sessions to sessions.

Warning

Only the invoke_config of the main session will be applied. The invoke_config of the sessions in sessions will be ignored.

The same is true for get_form(). Only the form returned by the main session’s get_form() will be rendered.

sessions = ()

tuple of Session

break_states = ('error',)

tuple of Session.status on which further processing will be skipped.

process()

Real work is done here…

This is the place for your own session-code.