Suitable API Documentation

class suitable.api.Api(servers: str | list[str] | dict[str, dict[str, Any]], ignore_unreachable: bool = False, ignore_errors: bool = False, host_key_checking: bool = True, sudo: bool = False, dry_run: bool = False, verbosity: Verbosity = 'info', environment: dict[str, str] | None = None, strategy: Incomplete | None = None, collections_path: str | Sequence[str] | None = None, **options: Incomplete)[source]

Provides all available ansible modules as local functions:

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

Parameters:

servers –
A list of servers, a string with space-delimited servers or a dict with server name as key and ansible host variables as values. 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.

Examples of valid uses:
```
api = Api(['web.example.org', 'db.example.org'])
api = Api('web.example.org')
api = Api('web.example.org db.example.org')
api = Api({'web.example.org': {'ansible_host': '10.10.5.1'}})
api = Api(['example.org:2222', 'example.org:2223'])
```
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('example.org', 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. Possible values:
- debug
- info (default)
- warn
- error
- critical
environment –
The environment variables which should be set during when a module is executed. For example:
```
api = Api('example.org', environment={
    'PGPORT': '5432'
})
```
strategy –
The Ansible strategy to use. Defaults to None which lets Ansible decide which strategy it wants to use.

Note that you need to globally install strategy plugins using install_strategy_plugins() before using strategies provided by plugins.
collections_path –
Provide a custom path or sequence of path to look for ansible collections when loading/hooking the modules.

Ansible only initializes the module loader once, so it’s not possible to have multiple Api instances with different values for this parameter. The first one will always be the one that matters.

Additionally if the loader has already been initialized prior to the creation of the Api instance, then this parameter has no effect at all.

Requires ansible-core >= 2.15
host_key_checking – Set to false to disable host key checking.

extra_vars –

Extra variables available to Ansible. 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')

This can be used to specify an alternative Python interpreter:

api = Api('example.org', extra_vars={
    'ansible_python_interpreter': '/path/to/interpreter'
})

**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

on_unreachable_host(module: str, host: str) → NoReturn[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.

on_module_error(module: str, host: str, result: ResultData) → NoReturn[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.

valid_return_codes(*codes: int) → Generator[None, None, None][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')

acl(*, path: StrPath, state: Literal['absent', 'present', 'query'] = 'query', follow: bool = True, default: bool = False, entity: str = '', etype: Literal['group', 'mask', 'other', 'user'] = ..., permissions: str = ..., entry: str = ..., recursive: bool = False, use_nfsv4_acls: bool = False, recalculate_mask: Literal['default', 'mask', 'no_mask'] = 'default') → AclResults

Set and retrieve file ACL information.

See also

ansible.posix

Parameters:

path – The full path of the file or object.
state – Define whether the ACL should be present or not. The query state gets the current ACL without changing it, for use in register operations.
follow – Whether to follow symlinks on the path if a symlink is encountered.
default – If the target is a directory, setting this to true will make it the default ACL for entities created inside the directory. Setting default to true causes an error if the path is a file.
entity – The actual user or group that the ACL applies to when matching entity types user or group are selected.
etype – The entity type of the ACL to apply, see setfacl documentation for more info.
permissions – The permissions to apply/remove can be any combination of r, w, x. (read, write and execute respectively), and X (execute permission if the file is a directory or already has execute permission for some user).
entry – DEPRECATED. The ACL to set or remove. This must always be quoted in the form of <etype>:<qualifier>:<perms>. The qualifier may be empty for some types, but the type and perms are always required. - can be used as placeholder when you do not care about permissions. This is now superseded by entity, type and permissions fields.
recursive – Recursively sets the specified ACL. Incompatible with state=query. Alias recurse added in version 1.3.0.
use_nfsv4_acls – Use NFSv4 ACLs instead of POSIX ACLs.
recalculate_mask – Select if and when to recalculate the effective right masks of the files. See setfacl documentation for more info. Incompatible with state=query.

add_host(*, name: str, groups: Sequence[str] = ...) → AddHostResults

Add a host (and alternatively a group) to the ansible-playbook in-memory inventory.

See also