transactions.basic

Provides basic transactions.

Functions

simple_automation.transactions.basic.copy(context: simple_automation.context.Context, src: str, dst: str, mode=None, owner=None, group=None)

Copies the given src file to the remote host at dst.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • src (str) – The local source file path relative to the project directory. Will be templated.

  • dst (str) – The remote destination file path. Will be templated.

  • mode (int, optional) – The new file mode. Defaults the current context file creation mode.

  • owner (str, optional) – The new file owner. Defaults the current context owner.

  • group (str, optional) – The new file group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.copy_all(context: simple_automation.context.Context, src_dst_pairs: list, mode=None, owner=None, group=None)

Copies each (src, dst) list entry, as if copy() was called for each of them.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • src_dst_pairs (list[(str, str)]) – A list of (src, dst) pairs corresponding to the parameters from copy().

  • mode (int, optional) – The new file mode. Defaults the current context file creation mode.

  • owner (str, optional) – The new file owner. Defaults the current context owner.

  • group (str, optional) – The new file group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.directory(context: simple_automation.context.Context, path: str, mode=None, owner=None, group=None)

Creates the given directory on the remote.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • path (str) – The directory path to create (will be templated). Parent directory must exist.

  • mode (int, optional) – The new directory mode. Defaults the current context directory creation mode.

  • owner (str, optional) – The new directory owner. Defaults the current context owner.

  • group (str, optional) – The new directory group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.directory_all(context: simple_automation.context.Context, paths: list, mode=None, owner=None, group=None)

Creates the given directories as if directory() was called for each of them.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • paths (str) – The directory paths to create (each will be templated). Parent directory must exist for each directory. Executed in order.

  • mode (int, optional) – The new directory mode. Defaults the current context directory creation mode.

  • owner (str, optional) – The new directory owner. Defaults the current context owner.

  • group (str, optional) – The new directory group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.group(context: simple_automation.context.Context, name: str, state: str = 'present', system: bool = False)

Creates or deletes a unix group.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • name (str) – The name of the user to create or modify. Will be templated.

  • state (str) – If “present” the user will be added / modified, if “absent” the user will be deleted ignoring all other parameters.

  • system (bool) – If True the user will be created as a system user. This has no effect on existing users.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.save_output(context: simple_automation.context.Context, command: list, dst: str, desc=None, mode=None, owner=None, group=None)

Saves the stdout of the given command on the remote host at remote dst. Using –pretend will still run the command, but won’t save the output. Changed status reflects if the file contents changed. Optionally accepts file mode, owner and group, if not given, context defaults are used.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • command (list[str]) – A list containing the command and its arguments. Each one will be templated.

  • dst (str) – The remote destination file path. Will be templated.

  • desc (str) – A description to be printed in the summary when executing.

  • mode (int, optional) – The new file mode. Defaults the current context file creation mode.

  • owner (str, optional) – The new file owner. Defaults the current context owner.

  • group (str, optional) – The new file group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.template(context: simple_automation.context.Context, dst: str, src: Optional[str] = None, content: Optional[str] = None, mode=None, owner=None, group=None)

Templates the given src file or given content and copies the output to the remote host at dst. Either content or src must be specified.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • src (str, optional) – The local source file path relative to the project directory. Will be templated. Mutually exclusive with content.

  • content (str, optional) – The content for the file. Will be templated. Mutually exclusive with src.

  • dst (str) – The remote destination file path. Will be templated.

  • mode (int, optional) – The new file mode. Defaults the current context file creation mode.

  • owner (str, optional) – The new file owner. Defaults the current context owner.

  • group (str, optional) – The new file group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.template_all(context: simple_automation.context.Context, src_dst_pairs: list, mode=None, owner=None, group=None)

Templates each (src, dst) list entry, as if template() was called for each of them.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • src_dst_pairs (list[(str, str)]) – A list of (src, dst) pairs corresponding to the parameters from template().

  • mode (int, optional) – The new file mode. Defaults the current context file creation mode.

  • owner (str, optional) – The new file owner. Defaults the current context owner.

  • group (str, optional) – The new file group. Defaults the current context group.

Returns

The completed transaction

Return type

CompletedTransaction

simple_automation.transactions.basic.user(context: simple_automation.context.Context, name: str, group: Optional[str] = None, groups: Optional[list] = None, append_groups: bool = False, state: str = 'present', system: bool = False, shell: Optional[str] = None, password: Optional[str] = None, home: Optional[str] = None, create_home=True)

Creates or modifies a unix user. Because we interally call userdel, removing a user will also remove it’s associated primary group if no other user belongs to it.

Parameters
  • context (Context) – The context providing the execution context and templating dictionary.

  • name (str) – The name of the user to create or modify. Will be templated.

  • group (str, optional) – The primary group of the user. If given, the group must already exists. Otherwise, a group will be created with the same name as the user, if a user is created by this action. Will be templated.

  • groups (list[str], optional) – Supplementary groups for the user.

  • append_groups (bool) – If True, the user will be added to all given supplementary groups. If False, the user will be added to exactly the given supplementary groups and removed from other groups.

  • state (str) – If “present” the user will be added / modified, if “absent” the user will be deleted ignoring all other parameters.

  • system (bool) – If True the user will be created as a system user. This has no effect on existing users.

  • shell (str) – Specifies the shell for the user. Defaults to /sbin/nologin if not given but a user needs to be created. Will be templated.

  • password (str, optional) –

    Will update the password hash to the given vaule of the user. Use ! to lock the account. Defaults to ‘!’ if not given but a user needs to be created. Will be templated. You can generate a password hash by using the following script:

    >>> import crypt, getpass
    >>> crypt.crypt(getpass.getpass(), crypt.mksalt(crypt.METHOD_SHA512))
    '$6$rwn5z9MlYvcnE222$9wOP6Y6EcnF.cZ7BUjttWeSQNdOQWI...'
    

  • home (str, optional) – The home directory for the user. Will be left empty if not given but a user needs to be created. Will be templated.

  • create_home (bool) – If True and home was given, create the home directory of the user if it doesn’t exist.

Returns

The completed transaction

Return type

CompletedTransaction