Ansible compatability for well known file operations lineinfile, blockinfile and template #1477
Description
Ansible compatability
Many Pyinfra operations have direct equivalences in Ansible builtins. The parameters of those operations and their functionality should be identical to Ansible. The Ansible modules have been designed to provide idempotent file updates on the host. They are are well understood in the DevOps community. There is no reason for them not to be identical.
For example, in Pyinfra
files.block(
path: str, content: str | list[str] | None=None, present=True, line: str | None=None,
backup=False, escape_regex_characters=False, try_prevent_shell_expansion=False,
before=False, after=False, marker: str | None=None, begin: str | None=None,
end: str | None=None, **kwargs,
)
Is equivalent to the ansible.builtin.blockinfile module.
It should have attributes that match the Ansible implementation:
Attributes:
path (str): The path to the file to modify.
block (str, optional): The text to insert inside the marker lines. If empty or None,
the block will be removed if `state="absent"`. Defaults to ``""``.
marker (str, optional): The marker line template. `{mark}` will be replaced with the values
in `marker_begin` (default="BEGIN") and `marker_end` (default="END").
Defaults to ``"# {mark} ANSIBLE MANAGED BLOCK"``.
marker_begin (str, optional): The text to replace `{mark}` in the opening marker line.
Defaults to ``"BEGIN"``.
marker_end (str, optional): The text to replace `{mark}` in the closing marker line.
Defaults to ``"END"``.
state (str, optional): Whether the block should be present or absent. Choices are:
- "present" (default): Ensure the block exists.
- "absent": Remove the block if it exists.
Defaults to ``"present"``.
create (bool, optional): Create a new file if it does not exist. Defaults to ``False``.
insertafter (str, optional): Insert the block after the last match of the specified regular
expression. Special value "EOF" inserts the block at the end of
the file. Defaults to ``None``.
insertbefore (str, optional): Insert the block before the last match of the specified regular
expression. Special value "BOF" inserts the block at the beginning
of the file. Defaults to ``None``.
append_newline (bool, optional): Append a blank line to the inserted block if this does not
appear at the end of the file. Defaults to ``False``.
prepend_newline (bool, optional): Prepend a blank line to the inserted block if this does not
appear at the beginning of the file. Defaults to ``False``.
backup (bool, optional): Create a backup file including the timestamp information so the original
file can be restored if needed. Defaults to ``False``.
attrs (dict, optional): A dictionary containing file attributes to set, such as permissions,
owner, and group. Example: ``{"permissions": 0o644, "owner": "root",
"group": "root"}``. Defaults to an empty dictionary.
unsafe_writes (bool, optional): Allow unsafe writes if atomic operations fail. Defaults to ``False``.
Similarly, files.line should have the same attributes and functionality as ansible.builtin.lineinfile. files.template should have the same attributes and functionality as ansible.builtin.template.
Reference implementations, of the Ansible functionality in Python, are provided: