Suitable API Documentation

class suitable.api.Api(servers, ignore_unreachable=False, ignore_errors=False, sudo=False, dry_run=False, verbosity='info', **options)[source]

The api is a proxy to the Ansible API.

It provides all available ansible modules as local functions:

api = Api('personal.server.dev')
api.sync(src='/Users/denis/.zshrc', dest='/home/denis/.zshrc')

Initializes the api.

Parameters:
  • servers –

    A list of servers or a string with space-delimited servers. The api instances will operate on these servers only. Servers which cannot be reached or whose use triggers an error are taken out of the list for the lifetime of the object.

    e.g: ['server1', 'server2'] or 'server' or 'server1 server2'.

  • ignore_unreachable – If true, unreachable servers will not trigger an exception. They are however still taken out of the list for the lifetime of the object.
  • ignore_errors – If true, errors on servers will not trigger an exception. Servers who trigger an error are still ignored for the lifteime of the object.
  • sudo –

    If true, the commands run as root using sudo. This is a shortcut for the following:

    Api('server', become=True, become_user='root')

    If become or become_user are passed, this option is ignored!

  • sudo_pass – If given, sudo is invoked with the given password. Alternatively you can use Ansible’s builtin password option (e.g. passwords={‘become_pass’: ‘***’}).
  • remote_pass –

    Passwords are passed to ansible using the passwords dictionary by default (e.g. passwords={‘conn_pass’: ‘****‘}). Since this is a bit cumbersome and because earlier Suitable releases supported remote_pass this convenience argument exists.

    If passwords is passed, the remote_pass argument is ignored.

  • dry_run – Runs ansible in ‘check’ mode, where no changes are actually applied to the server(s).
  • verbosity –

    The verbosity level of ansible. Either ‘critical’, ‘error’, ‘warn’, ‘info’ or ‘debug’.

    Defaults to ‘info’.

  • **options –

    All remining keyword arguments are passed to the Ansible TaskQueueManager. The available options are listed here:

    http://docs.ansible.com/ansible/developing_api.html

    A common option would be to use the commands on the server as a different user using sudo:

    Api('webserver', become=True, become_user='www-data')

    You can also add extra variables. Note that those will be global and not bound to any particular host:

    api = Api('webserver', extra_vars={'home': '/home/denis'})
api.file(dest="{{ home }}/.zshrc", state='touch')
on_module_error(module, host, result)[source]

If you want to customize your error handling, this would be the point to write your own method in a subclass.

Note that this method is not called if ignore_errors is True.

If the return value of this method is ‘keep-trying’, the server will not be ignored for the lifetime of the object. This enables you to practically write your own flavor of ‘ignore_errors’.

If an any exception is raised the server WILL be ignored.

on_unreachable_host(module, host)[source]

If you want to customize your error handling, this would be the point to write your own method in a subclass.

Note that this method is not called if ignore_unreachable is True.

If the return value of this method is ‘keep-trying’, the server will not be ignored for the lifetime of the object. This enables you to practically write your own flavor of ‘ignore_unreachable’.

If an any exception is raised the server WILL be ignored.

valid_return_codes(*args, **kwds)[source]

Sets codes which are considered valid when returned from command modules. The default is (0, ).

Should be used as a context:

with api.valid_return_codes(0, 1):
    api.shell('test -e /tmp/log && rm /tmp/log')