ansible-systemd/plugins/modules/timer.py

#!/usr/bin/python3
import pathlib
from typing import List, Union

try:
    from ansible_module.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, modspec
    from ansible_module.module_utils.module import SystemdReloadMixin, SystemdUnitModule, installable
except ImportError:
    from ansible_collections.sebastian.base.plugins.module_utils.generic import SYSTEMD_SERVICE_CONFIG, Types, modspec
    from ansible_collections.sebastian.base.plugins.module_utils.module import SystemdReloadMixin, SystemdUnitModule, installable


__module_name__ = "TimerModule"


@installable
class TimerModule(SystemdUnitModule, SystemdReloadMixin):  # type: ignore[misc]
    """Creates Timer units"""

    name = "timer"
    module_spec = modspec(
        argument_spec=dict(
            name=Types.str(required=True, help="Name of the unit"),
            description=Types.str(help="Description of the timer"),
            onactive=Types.list(
                help="Starts the service x seconds after this timer was activated",
                elements=Types.str(),
            ),
            onboot=Types.list(
                help="Starts the service x seconds after the device was booted or the container was started",
                elements=Types.str(),
            ),
            onstartup=Types.list(
                help="Starts the service x seconds after the System's/User's systemd instance was started",
                elements=Types.str(),
            ),
            onunitactive=Types.list(
                help="Starts the service x seconds after the unit this timer activates was last activated",
                elements=Types.str(),
            ),
            onunitinactive=Types.list(
                help="Starts the service x seconds after the unit this timer activates was last deactivated",
                elements=Types.str(),
            ),
            oncalendar=Types.list(
                help="Uses an Time string to start the unit.",
                elements=Types.str(),
            ),
            persistent=Types.bool(
                help="If the system was down in the time the timer would have started the unit, start the unit as soon as possible."
            ),
            randomdelay=Types.str(help="delays the activation by an random delay between 0 and the value"),
            fixdelay=Types.bool(
                help="set the random delay to an fixed value. It uses the timername, the user of the servicemanager and the machineid as the seed."
            ),
            unit=Types.str(help="The name of the unit. only needed if its not {{name}}.service"),
        ),
        required_one_of=[
            (
                "onactive",
                "onboot",
                "onstartup",
                "onunitactive",
                "onunitinactive",
                "oncalendar",
            ),
        ],
    )

    def prepare(self):
        self.unitfile = (SYSTEMD_SERVICE_CONFIG / self.get("name")).with_suffix(".timer")
        self.__unit = None

    def body(self):
        section = "[Timer]\n"
        params = []
        params.extend(
            self.map_param(
                onactive="OnActiveSec",
                onboot="OnBootSec",
                onstartup="OnStartupSec",
                onunitactive="OnUnitActiveSec",
                onunitinactive="OnUnitInactiveSec",
                oncalendar="OnCalendar",
                persistent="Persistent",
                randomdelay="RandomizedDelaySec",
                fixdelay="FixedRandomDelay",
                unit="Unit",
            ),
        )
        if len(params) == 0:
            return None
        section += "".join(params)
        return section

    def unit(self) -> str:
        if self.__unit is None:
            self.__unit = self._unit(
                self.header(),
                self.body(),
                self.install(),  # type: ignore[call-arg,misc]
            )
        return self.__unit


DOCUMENTATION = """---
description:
- Creates Timer units
module: timer
options:
  after:
    default: []
    description:
    - list of units that this unit wants to be started after this unit
    elements: str
    required: false
    type: list
  before:
    default: []
    description:
    - list of units that this unit needs to be started before this unit.
    elements: str
    required: false
    type: list
  description:
    description:
    - Description of the timer
    required: false
    type: str
  documentation:
    default: []
    description:
    - Paths where documentation can be found
    elements: str
    required: false
    type: list
  fixdelay:
    description:
    - set the random delay to an fixed value. It uses the timername, the user of the
      servicemanager and the machineid as the seed.
    required: false
    type: bool
  name:
    description:
    - Name of the unit
    required: true
    type: str
  onactive:
    default: []
    description:
    - Starts the service x seconds after this timer was activated
    elements: str
    required: false
    type: list
  onboot:
    default: []
    description:
    - Starts the service x seconds after the device was booted or the container was
      started
    elements: str
    required: false
    type: list
  oncalendar:
    default: []
    description:
    - Uses an Time string to start the unit.
    elements: str
    required: false
    type: list
  onstartup:
    default: []
    description:
    - Starts the service x seconds after the System's/User's systemd instance was
      started
    elements: str
    required: false
    type: list
  onunitactive:
    default: []
    description:
    - Starts the service x seconds after the unit this timer activates was last activated
    elements: str
    required: false
    type: list
  onunitinactive:
    default: []
    description:
    - Starts the service x seconds after the unit this timer activates was last deactivated
    elements: str
    required: false
    type: list
  partof:
    default: []
    description:
    - list of units that this unit is part of.
    - If the restart this unit does it too, but if this restarts it does not affect
      the other units.
    elements: str
    required: false
    type: list
  persistent:
    description:
    - If the system was down in the time the timer would have started the unit, start
      the unit as soon as possible.
    required: false
    type: bool
  randomdelay:
    description:
    - delays the activation by an random delay between 0 and the value
    required: false
    type: str
  required_by:
    default: []
    description:
    - systemd units that require this mount
    elements: str
    required: false
    type: list
  requires:
    default: []
    description:
    - list of units that this unit requires. If it fails or can't be started this
      unit fails. without before/after this is started at the same time
    elements: str
    required: false
    type: list
  unit:
    description:
    - The name of the unit. only needed if its not {{name}}.service
    required: false
    type: str
  wanted_by:
    default: []
    description:
    - systemd units that want the mount, but not explicitly require it. Commonly used
      for target if not service explicitly require it.
    elements: str
    required: false
    type: list
  wants:
    default: []
    description:
    - list of units that this unit wants. If it fails or can't be started it does
      not affect this unit
    elements: str
    required: false
    type: list
short_description: Creates Timer units
"""

if __name__ == "__main__":
    TimerModule()()