dron 0.1.20241008__py3-none-any.whl

dron/__init__.py

@@ -0,0 +1,6 @@
+# NOTE: backwards compatibility, now relying on dron.__main__
+# should probably remove this later
+from .dron import main
+
+if __name__ == '__main__':
+    main()

dron/__main__.py

@@ -0,0 +1,5 @@
+# NOTE: import needs to be on top level as it's the entry point
+from .dron import main
+
+if __name__ == '__main__':
+    main()

dron/api.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import getpass
+import inspect
+import re
+import sys
+from dataclasses import dataclass
+from typing import Sequence
+
+from .common import (
+    IS_SYSTEMD,
+    Command,
+    OnCalendar,
+    When,
+    wrap,
+)
+
+OnFailureAction = str
+
+UnitName = str
+
+@dataclass
+class Job:
+    when: When | None
+    command: Command
+    unit_name: UnitName
+    on_failure: Sequence[OnFailureAction]
+    kwargs: dict[str, str]
+
+
+# staticmethod isn't callable directly prior to 3.10
+def _email(to: str) -> str:
+    return f'{sys.executable} -m dron.notify.email --job %n --to {to}'
+
+
+class notify:
+    @staticmethod
+    def email(to: str) -> str:
+        return _email(to)
+
+    email_local = _email(to='%u' if IS_SYSTEMD else getpass.getuser())
+
+    # TODO adapt to macos
+    desktop_notification = f'{sys.executable} -m dron.notify.ntfy_desktop --job %n'
+
+    telegram = f'{sys.executable} -m dron.notify.telegram --job %n'
+
+
+def job(
+    when: When | None,
+    command: Command,
+    *,
+    unit_name: str | None = None,
+    on_failure: Sequence[OnFailureAction] = (notify.email_local,),
+    **kwargs,
+) -> Job:
+    """
+    when: if None, then timer won't be created (still allows running job manually)
+    unit_name: if None, then will attempt to guess from source code (experimental!)
+    """
+    assert 'extra_email' not in kwargs, unit_name  # deprecated
+
+    stacklevel: int = kwargs.pop('stacklevel', 1)
+
+    def guess_name() -> str | Exception:
+        stack = inspect.stack()
+        frame = stack[stacklevel + 1]  # +1 for guess_name itself
+        code_context_lines = frame.code_context
+        # python should alway keep single line for code context? but just in case
+        if code_context_lines is None or len(code_context_lines) != 1:
+            return RuntimeError(f"Expected single code context line, got {code_context_lines=}")
+        [code_context] = code_context_lines
+        code_context = code_context.strip()
+        rgx = r'(\w+)\s+='
+        m = re.match(rgx, code_context)  # find assignment to variable
+        if m is None:
+            return RuntimeError(f"Couldn't guess from {code_context=} (regex {rgx=})")
+        return m.group(1)
+
+    if unit_name is None:
+        guessed_name = guess_name()
+
+        if isinstance(guessed_name, Exception):
+            raise RuntimeError(f"{when} {command}: couldn't guess job name: {guessed_name}")
+
+        unit_name = guessed_name
+
+    return Job(
+        when=when,
+        command=command,
+        unit_name=unit_name,
+        on_failure=on_failure,
+        kwargs=kwargs,
+    )
+
+
+__all__ = (
+    'When',
+    'OnCalendar',
+    'OnFailureAction',
+    'Command',
+    'wrap',
+    'job',
+    'notify',
+    'Job',  # todo maybe don't expose it?
+)

dron/cli.py

@@ -0,0 +1,382 @@
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from pprint import pprint
+from tempfile import TemporaryDirectory
+
+import click
+
+from . import launchd, systemd
+from .api import UnitName
+from .common import (
+    IS_SYSTEMD,
+    MANAGED_MARKER,
+    MonitorParams,
+    Unit,
+    escape,
+    logger,
+    print_monitor,
+)
+from .dron import (
+    DRONTAB,
+    apply,
+    do_lint,
+    drontab_dir,
+    get_entries_for_monitor,
+    load_jobs,
+    manage,
+    managed_units,
+)
+
+
+def cmd_edit() -> None:
+    drontab = DRONTAB
+    if not drontab.exists():
+        if click.confirm(f"tabfile {drontab} doesn't exist. Create?", default=True):
+            drontab.write_text(
+                '''\
+#!/usr/bin/env python3
+from dron.api import job
+
+def jobs():
+    # yield job(
+    #     'hourly',
+    #     '/bin/echo 123',
+    #     unit_name='test_unit'
+    # )
+    pass
+'''.lstrip()
+            )
+        else:
+            raise RuntimeError()
+
+    editor = os.environ.get('EDITOR')
+    if editor is None:
+        logger.warning('No EDITOR! Fallback to nano')
+        editor = 'nano'
+
+    with TemporaryDirectory() as tdir:
+        tpath = Path(tdir) / 'drontab'
+        shutil.copy2(drontab, tpath)
+
+        orig_mtime = tpath.stat().st_mtime
+        while True:
+            res = subprocess.run([editor, str(tpath)], check=True)
+
+            new_mtime = tpath.stat().st_mtime
+            if new_mtime == orig_mtime:
+                logger.warning('No notification made')
+                return
+
+            ex: Exception | None = None
+            try:
+                state = do_lint(tabfile=tpath)
+            except Exception as e:
+                logger.exception(e)
+                ex = e
+            else:
+                try:
+                    manage(state=state)
+                except Exception as ee:
+                    logger.exception(ee)
+                    ex = ee
+            if ex is not None:
+                if click.confirm('Got errors. Try again?', default=True):
+                    continue
+                raise ex
+
+            drontab.write_text(tpath.read_text())  # handles symlinks correctly
+            logger.info(f"Wrote changes to {drontab}. Don't forget to commit!")
+            break
+
+        # TODO show git diff?
+        # TODO perhaps allow to carry on regardless? not sure..
+        # not sure how much we can do without modifying anything...
+
+
+def cmd_lint(tabfile: Path) -> None:
+    _state = do_lint(tabfile)
+    logger.info('all good')
+
+
+def cmd_apply(tabfile: Path) -> None:
+    apply(tabfile)
+
+
+def cmd_print(*, tabfile: Path, pretty: bool) -> None:
+    dtab_dir = Path(drontab_dir())
+    jobs = list(load_jobs(tabfile=tabfile, ppath=dtab_dir))
+
+    if pretty:
+        import tabulate
+
+        items = [
+            {
+                'UNIT': job.unit_name,
+                'SCHEDULE': job.when,
+                'COMMAND': escape(job.command),
+            }
+            for job in jobs
+        ]
+        print(tabulate.tabulate(items, headers="keys"))
+    else:
+        for j in jobs:
+            print(j)
+
+
+def cmd_run(*, unit: Unit, do_exec: bool) -> None:
+    if IS_SYSTEMD:
+        return systemd.cmd_run(unit=unit, do_exec=do_exec)
+    else:
+        return launchd.cmd_run(unit=unit, do_exec=do_exec)
+
+
+def cmd_past(unit: Unit) -> None:
+    if IS_SYSTEMD:
+        return systemd.cmd_past(unit)
+    else:
+        return launchd.cmd_past(unit)
+
+
+# TODO think if it's worth integrating with timers?
+def cmd_monitor(params: MonitorParams) -> None:
+    managed = list(managed_units(with_body=False))  # body slows down this call quite a bit
+    if len(managed) == 0:
+        logger.warning('no managed units!')
+
+    logger.debug('starting monitor...')
+
+    entries = get_entries_for_monitor(managed=managed, params=params)
+    print_monitor(entries)
+
+
+# TODO test it on CI?
+def _drontab_example() -> str:
+    return '''
+from dron.api import job
+
+# at the moment you're expected to define jobs() function that yields jobs
+# in the future I might add more mechanisms
+def jobs():
+    # simple job that doesn't do much
+    yield job(
+        'daily',
+        '/home/user/scripts/run-borg /home/user',
+        unit_name='borg-backup-home',
+    )
+
+    yield job(
+        'daily',
+        'linkchecker https://beepb00p.xyz',
+        unit_name='linkchecker-beepb00p',
+    )
+
+    # drontab is simply python code!
+    # so if you're annoyed by having to rememver Systemd syntax, you can use a helper function
+    def every(*, mins: int) -> str:
+        return f'*:0/{mins}'
+
+    # make sure my website is alive, it will send local email on failure
+    yield job(
+        every(mins=10),
+        'ping https://beepb00p.xyz',
+        unit_name='ping-beepb00p',
+    )
+'''.lstrip()
+
+
+def make_parser() -> argparse.ArgumentParser:
+    from .common import VerifyOff
+
+    def add_verify(p: argparse.ArgumentParser) -> None:
+        # specify in readme???
+        # would be nice to use external checker..
+        # https://github.com/systemd/systemd/issues/8072
+        # https://unix.stackexchange.com/questions/493187/systemd-under-ubuntu-18-04-1-fails-with-failed-to-create-user-slice-serv
+        p.add_argument('--no-verify', action=VerifyOff, nargs=0, help='Skip systemctl verify step')
+
+    p = argparse.ArgumentParser(
+        prog='dron',
+        description='''
+dron -- simple frontend for Systemd, inspired by cron.
+
+- *d* stands for 'Systemd'
+- *ron* stands for 'cron'
+
+dron is my attempt to overcome things that make working with Systemd tedious
+'''.lstrip(),
+        formatter_class=lambda prog: argparse.RawTextHelpFormatter(prog, width=100),
+    )
+    # TODO ugh. when you type e.g. 'dron apply', help format is wrong..
+    example = ''.join(': ' + l for l in _drontab_example().splitlines(keepends=True))
+    # TODO begin_src python maybe?
+    p.epilog = f'''
+* What does it do?
+In short, you type ~dron edit~ and edit your config file, similarly to ~crontab -e~:
+
+{example}
+
+After you save your changes and exit the editor, your drontab is checked for syntax and applied
+
+- if checks have passed, your jobs are mapped onto Systemd units and started up
+- if there are potential errors, you are prompted to fix them before retrying
+
+* Why?
+In short, because I want to benefit from the heavy lifting that Systemd does: timeouts, resource management, restart policies, powerful scheduling specs and logging,
+while not having to manually manipulate numerous unit files and restart the daemon all over.
+
+I elaborate on what led me to implement it and motivation [[https://beepb00p.xyz/scheduler.html#what_do_i_want][here]]. Also:
+
+- why not just use [[https://beepb00p.xyz/scheduler.html#cron][cron]]?
+- why not just use [[https://beepb00p.xyz/scheduler.html#systemd][systemd]]?
+    '''
+
+    p.add_argument(
+        '--marker', required=False, help=f'Use custom marker instead of default `{MANAGED_MARKER}`. Useful for developing/testing.'
+    )
+
+    def add_tabfile_arg(p: argparse.ArgumentParser) -> None:
+        p.add_argument('tabfile', type=Path, nargs='?')
+
+    sp = p.add_subparsers(dest='mode')
+
+    ### actions on drontab file
+    edit_parser = sp.add_parser('edit', help="Edit drontab (like 'crontab -e')")
+    add_verify(edit_parser)
+
+    apply_parser = sp.add_parser('apply', help="Apply drontab (like 'crontab' with no args)")
+    add_tabfile_arg(apply_parser)
+    add_verify(apply_parser)
+    # TODO --force?
+    lint_parser = sp.add_parser('lint', help="Check drontab (no 'crontab' alternative, sadly!)")
+    add_tabfile_arg(lint_parser)
+    add_verify(lint_parser)
+
+    print_parser = sp.add_parser('print', help="Parse and print drontab")
+    add_tabfile_arg(print_parser)
+    print_parser.add_argument('--pretty', action='store_true')
+    ###
+
+    ### actions on managed jobs
+    debug_parser = sp.add_parser('debug', help='Print some debug info')
+
+    uninstall_parser = sp.add_parser('uninstall', help="Uninstall all managed jobs")
+    add_verify(uninstall_parser)
+
+    run_parser = sp.add_parser('run', help='Run the job right now, ignoring the timer')
+    run_parser.add_argument('unit', type=str, nargs='?')  # TODO add shell completion?
+    run_parser.add_argument('--exec', action='store_true', dest='do_exec', help='Run directly, not via systemd/launchd')
+
+    past_parser = sp.add_parser('past', help='List past job runs')
+    past_parser.add_argument('unit', type=str, nargs='?')  # TODO add shell completion?
+    ###
+
+    ### misc actions
+    mp = sp.add_parser('monitor', help='Monitor services/timers managed by dron')
+    mp.add_argument('-n', type=int, default=1, help='refresh every n seconds')
+    mp.add_argument('--once', action='store_true', help='only call once')
+    mp.add_argument('--rate', action='store_true', help='Display success rate (unstable and potentially slow)')
+    mp.add_argument('--command', action='store_true', help='Display command')
+    ###
+    return p
+
+
+def main() -> None:
+    from .cli import make_parser
+
+    p = make_parser()
+    args = p.parse_args()
+
+    marker: str | None = args.marker
+    if marker is not None:
+        from . import common
+
+        common.MANAGED_MARKER = marker
+
+    mode: str = args.mode
+
+    def tabfile_or_default() -> Path:
+        tabfile = args.tabfile
+        if tabfile is None:
+            tabfile = DRONTAB
+        return tabfile
+
+    def prompt_for_unit() -> UnitName:
+        from prompt_toolkit import PromptSession
+        from prompt_toolkit.completion import WordCompleter
+
+        # TODO print options
+        managed = list(managed_units(with_body=False))
+        units = [x.unit_file.stem for x in managed]
+
+        print('Units under dron:', file=sys.stderr)
+        for u in units:
+            print(f'- {u}', file=sys.stderr)
+
+        completer = WordCompleter(units, ignore_case=True)
+        session = PromptSession("Select a unit: ", completer=completer)  # type: ignore[var-annotated]
+        selected = session.prompt()
+        return selected
+
+    if mode == 'edit':
+        cmd_edit()
+    elif mode == 'apply':
+        tabfile = tabfile_or_default()
+        cmd_apply(tabfile)
+    elif mode == 'lint':
+        tabfile = tabfile_or_default()
+        cmd_lint(tabfile)
+    elif mode == 'print':
+        tabfile = tabfile_or_default()
+
+        from .cli import cmd_print  # lazy due to circular import
+
+        cmd_print(tabfile=tabfile, pretty=args.pretty)
+    elif mode == 'debug':
+        managed = managed_units(with_body=False)  # TODO not sure about body
+        for x in managed:
+            pprint(x, stream=sys.stderr)
+    elif mode == 'uninstall':
+        click.confirm('Going to remove all dron managed jobs. Continue?', default=True, abort=True)
+        with TemporaryDirectory() as td:
+            empty = Path(td) / 'empty'
+            empty.write_text(
+                '''\
+def jobs():
+    yield from []
+'''
+            )
+            cmd_apply(empty)
+    elif mode == 'run':
+        unit = args.unit if args.unit is not None else prompt_for_unit()
+        do_exec = args.do_exec
+        cmd_run(unit=unit, do_exec=do_exec)
+    elif mode == 'past':
+        unit = args.unit if args.unit is not None else prompt_for_unit()
+        cmd_past(unit=unit)
+    elif mode == 'monitor':
+        once = args.once
+
+        params = MonitorParams(
+            with_success_rate=args.rate,
+            with_command=args.command,
+        )
+
+        if once:
+            # fallback on old style monitor for now?
+            # this can be quite useful for grepping etc..
+            cmd_monitor(params=params)
+        else:
+            from .monitor import MonitorApp
+
+            app = MonitorApp(monitor_params=params, refresh_every=args.n)
+            app.run()
+    else:
+        logger.error(f'Unknown mode: {mode}')
+        p.print_usage(sys.stderr)
+        sys.exit(1)

dron/common.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import argparse
+import platform
+import shlex
+import sys
+from dataclasses import asdict, dataclass, replace
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, Iterable, Sequence, TypeVar, Union
+
+from loguru import logger  # noqa: F401
+
+datetime_aware = datetime
+datetime_naive = datetime
+
+
+# TODO can remove this? although might be useful for tests
+VERIFY_UNITS = True
+# TODO ugh. verify tries using already installed unit files so if they were bad, everything would fail
+# I guess could do two stages, i.e. units first, then timers
+# dunno, a bit less atomic though...
+
+class VerifyOff(argparse.Action):
+    def __call__(self, parser, namespace, values, option_string = None):  # noqa: ARG002
+        global VERIFY_UNITS
+        VERIFY_UNITS = False
+
+
+@dataclass
+class MonitorParams:
+    with_success_rate: bool
+    with_command: bool
+
+
+Unit = str
+Body = str
+UnitFile = Path
+
+
+@dataclass
+class UnitState:
+    unit_file: UnitFile
+    body: Body | None
+    cmdline: Sequence[str] | None  # can be None for timers
+
+
+@dataclass
+class LaunchdUnitState(UnitState):
+    # NOTE: can legit be str (e.g. if unit was never ran before)
+    last_exit_code: str | None
+    pid: str | None
+    schedule: str | None
+
+
+State = Iterable[UnitState]
+
+
+IS_SYSTEMD = platform.system() != 'Darwin'  # if not systemd it's launchd
+
+
+
+T = TypeVar('T')
+def unwrap(x: T | None) -> T:
+    assert x is not None
+    return x
+
+
+PathIsh = Union[str, Path]
+
+# if it's an str, assume it's already escaped
+# otherwise we are responsible for escaping..
+Command = Union[PathIsh, Sequence[PathIsh]]
+
+
+OnCalendar = str
+TimerSpec = Dict[str, str] # meh # TODO why is it a dict???
+ALWAYS = 'always'
+When = Union[OnCalendar, TimerSpec]
+
+
+MANAGED_MARKER = '(MANAGED BY DRON)'
+def is_managed(body: str) -> bool:
+    # switching off it because it's unfriendly to launchd
+    legacy_marker = '<MANAGED BY DRON>'
+    return MANAGED_MARKER in body or legacy_marker in body
+
+
+
+pytest_fixture: Any
+under_pytest = 'pytest' in sys.modules
+if under_pytest:
+    import pytest
+    pytest_fixture = pytest.fixture
+else:
+    pytest_fixture = lambda f: f # no-op otherwise to prevent pytest import
+
+
+Escaped = str
+def escape(command: Command) -> Escaped:
+    if isinstance(command, Escaped):
+        return command
+    elif isinstance(command, Path):
+        return escape([command])
+    else:
+        return ' '.join(shlex.quote(str(part)) for part in command)
+
+
+def wrap(script: PathIsh, command: Command) -> Escaped:
+    return shlex.quote(str(script)) + ' ' + escape(command)
+
+
+def test_wrap() -> None:
+    assert wrap('/bin/bash', ['-c', 'echo whatever']) == "/bin/bash -c 'echo whatever'"
+    bin_ = Path('/bin/bash')
+    assert wrap(bin_, "-c 'echo whatever'") == "/bin/bash -c 'echo whatever'"
+    assert wrap(bin_, ['echo', bin_]) == "/bin/bash echo /bin/bash"
+    assert wrap('cat', bin_) == "cat /bin/bash"
+
+
+
+@dataclass(order=True)
+class MonitorEntry:
+    unit: str
+    status: str
+    left: str
+    next: str
+    schedule: str
+    command: str | None
+    pid: str | None
+
+    """
+    'status' is coming from systemd/launchd, and it's a string.
+
+    So status_ok should be used instead if you actually want to rely on something robust.
+    """
+    status_ok: bool
+
+
+def print_monitor(entries: Iterable[MonitorEntry]) -> None:
+    entries = sorted(
+        entries,
+        key=lambda e: (e.pid is None, e.status_ok, e),
+    )
+
+    import termcolor  # noqa: I001
+    import tabulate
+    tabulate.PRESERVE_WHITESPACE = True
+
+    headers = [
+        'UNIT',
+        'STATUS',
+        'LEFT',
+        'NEXT',
+        'SCHEDULE',
+    ]
+    with_command = any(x.command is not None for x in entries)
+    if with_command:
+        headers.append('COMMAND')
+
+    items = []
+    for e in entries:
+        e = replace(
+            e,
+            status=termcolor.colored(e.status, 'green' if e.status_ok else 'red'),
+        )
+        if e.pid is not None:
+            e = replace(
+                e,
+                next=termcolor.colored('running', 'yellow'),
+                left='--',
+            )
+        items.append(list(asdict(e).values())[:len(headers)])
+    print(tabulate.tabulate(items, headers=headers))

dron/conftest.py

@@ -0,0 +1,18 @@
+import pytest
+
+
+@pytest.fixture(scope='session', autouse=True)
+def disable_verify_units_if_no_systemd():
+    '''
+    If we can't use systemd, we need to suppress systemd-specific linting
+    '''
+    from . import common
+    from .systemd import _is_missing_systemd
+
+    reason = _is_missing_systemd()
+    if reason is not None:
+        common.VERIFY_UNITS = False
+    try:
+        yield
+    finally:
+        common.VERIFY_UNITS = True