dron 0.1.20241008__tar.gz

dron-0.1.20241008/.ci/release

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+'''
+Run [[file:scripts/release][scripts/release]] to deploy Python package onto [[https://pypi.org][PyPi]] and [[https://test.pypi.org][test PyPi]].
+
+The script expects =TWINE_PASSWORD= environment variable to contain the [[https://pypi.org/help/#apitoken][PyPi token]] (not the password!).
+
+The script can be run manually.
+It's also running as =pypi= job in [[file:.github/workflows/main.yml][Github Actions config]]. Packages are deployed on:
+- every master commit, onto test pypi
+- every new tag, onto production pypi
+
+You'll need to set =TWINE_PASSWORD= and =TWINE_PASSWORD_TEST= in [[https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets#creating-encrypted-secrets][secrets]]
+for Github Actions deployment to work.
+'''
+
+import os
+import sys
+from pathlib import Path
+from subprocess import check_call
+import shutil
+
+is_ci = os.environ.get('CI') is not None
+
+def main() -> None:
+    import argparse
+    p = argparse.ArgumentParser()
+    p.add_argument('--test', action='store_true', help='use test pypi')
+    args = p.parse_args()
+
+    extra = []
+    if args.test:
+        extra.extend(['--repository', 'testpypi'])
+
+    root = Path(__file__).absolute().parent.parent
+    os.chdir(root) # just in case
+
+    if is_ci:
+        # see https://github.com/actions/checkout/issues/217
+        check_call('git fetch --prune --unshallow'.split())
+
+    dist = root / 'dist'
+    if dist.exists():
+        shutil.rmtree(dist)
+
+    check_call(['python3', '-m', 'build'])
+
+    TP = 'TWINE_PASSWORD'
+    password = os.environ.get(TP)
+    if password is None:
+        print(f"WARNING: no {TP} passed", file=sys.stderr)
+        import pip_secrets
+        password = pip_secrets.token_test if args.test else pip_secrets.token # meh
+
+    check_call([
+        'python3', '-m', 'twine',
+        'upload', *dist.iterdir(),
+        *extra,
+    ], env={
+        'TWINE_USERNAME': '__token__',
+        TP: password,
+        **os.environ,
+    })
+
+
+if __name__ == '__main__':
+    main()

dron-0.1.20241008/.ci/run

@@ -0,0 +1,41 @@
+#!/bin/bash
+set -eu
+
+cd "$(dirname "$0")"
+cd .. # git root
+
+if ! command -v sudo; then
+    # CI or Docker sometimes doesn't have it, so useful to have a dummy
+    function sudo {
+        "$@"
+    }
+fi
+
+if [ -n "${CI-}" ]; then
+    # install OS specific stuff here
+    case "$OSTYPE" in
+    darwin*) 
+        # macos
+        :
+        ;;
+    cygwin* | msys* | win*)
+        # windows
+        :
+        ;;
+    *)
+        # must be linux?
+        # necessary for dbus-python
+        sudo DEBIAN_FRONTEND=noninteractive NEEDRESTART_SUSPEND=1 apt-get install --yes libdbus-1-dev libglib2.0-dev
+        ;;
+    esac
+fi
+
+
+PY_BIN="python3"
+# some systems might have python pointing to python3
+if ! command -v python3 &> /dev/null; then
+    PY_BIN="python"
+fi
+
+"$PY_BIN" -m pip install --user tox
+"$PY_BIN" -m tox --parallel --parallel-live "$@"

dron-0.1.20241008/.github/workflows/main.yml

@@ -0,0 +1,90 @@
+# see https://github.com/karlicoss/pymplate for up-to-date reference
+
+name: CI
+on:
+  push:
+    branches: '*'
+    tags: 'v[0-9]+.*' # only trigger on 'release' tags for PyPi
+    # Ideally I would put this in the pypi job... but github syntax doesn't allow for regexes there :shrug:
+    # P.S. fuck made up yaml DSLs.
+  pull_request: # needed to trigger on others' PRs
+  # Note that people who fork it need to go to "Actions" tab on their fork and click "I understand my workflows, go ahead and enable them".
+  workflow_dispatch: # needed to trigger workflows manually
+    # todo cron?
+    inputs:
+      debug_enabled:
+        type: boolean
+        description: 'Run the build with tmate debugging enabled (https://github.com/marketplace/actions/debugging-with-tmate)'
+        required: false
+        default: false
+
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        platform: [ubuntu-latest, macos-latest]
+        python-version: ['3.9', '3.10', '3.11', '3.12']
+        # vvv just an example of excluding stuff from matrix
+        # exclude: [{platform: macos-latest, python-version: '3.6'}]
+
+    runs-on: ${{ matrix.platform }}
+
+    steps:
+    # ugh https://github.com/actions/toolkit/blob/main/docs/commands.md#path-manipulation
+    - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+        fetch-depth: 0  # nicer to have all git history when debugging/for tests
+
+    - uses: mxschmitt/action-tmate@v3
+      if: ${{ github.event_name == 'workflow_dispatch' && inputs.debug_enabled }}
+
+    # explicit bash command is necessary for Windows CI runner, otherwise it thinks it's cmd...
+    - run: bash .ci/run
+
+    - if: matrix.platform == 'ubuntu-latest'  # no need to compute coverage for other platforms
+      uses: actions/upload-artifact@v4
+      with:
+        include-hidden-files: true
+        name: .coverage.mypy_${{ matrix.platform }}_${{ matrix.python-version }}
+        path: .coverage.mypy/
+
+
+  pypi:
+    runs-on: ubuntu-latest
+    needs: [build] # add all other jobs here
+
+    steps:
+    # ugh https://github.com/actions/toolkit/blob/main/docs/commands.md#path-manipulation
+    - run: echo "$HOME/.local/bin" >> $GITHUB_PATH
+
+    - uses: actions/setup-python@v5
+      with:
+        python-version: '3.8'
+
+    - uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: 'release to test pypi'
+      # always deploy merged master to test pypi
+      if: github.event_name != 'pull_request' && github.event.ref == 'refs/heads/master'
+      env:
+        TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD_TEST }}
+      run: pip3 install --user --upgrade build twine && .ci/release --test
+
+    - name: 'release to pypi'
+      # always deploy tags to release pypi
+      # NOTE: release tags are guarded by on: push: tags on the top
+      if: github.event_name != 'pull_request' && startsWith(github.event.ref, 'refs/tags')
+      env:
+        TWINE_PASSWORD: ${{ secrets.TWINE_PASSWORD }}
+      run: pip3 install --user --upgrade build twine && .ci/release

dron-0.1.20241008/.gitignore

@@ -0,0 +1,160 @@
+
+# Created by https://www.gitignore.io/api/python,emacs
+# Edit at https://www.gitignore.io/?templates=python,emacs
+
+### Emacs ###
+# -*- mode: gitignore; -*-
+*~
+\#*\#
+/.emacs.desktop
+/.emacs.desktop.lock
+*.elc
+auto-save-list
+tramp
+.\#*
+
+# Org-mode
+.org-id-locations
+*_archive
+
+# flymake-mode
+*_flymake.*
+
+# eshell files
+/eshell/history
+/eshell/lastdir
+
+# elpa packages
+/elpa/
+
+# reftex files
+*.rel
+
+# AUCTeX auto folder
+/auto/
+
+# cask packages
+.cask/
+dist/
+
+# Flycheck
+flycheck_*.el
+
+# server auth directory
+/server/
+
+# projectiles files
+.projectile
+
+# directory configuration
+.dir-locals.el
+
+# network security
+/network-security.data
+
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# End of https://www.gitignore.io/api/python,emacs

dron-0.1.20241008/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Dima Gerasimov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dron-0.1.20241008/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.1
+Name: dron
+Version: 0.1.20241008
+Author-email: "Dima Gerasimov (@karlicoss)" <karlicoss@gmail.com>
+Maintainer-email: "Dima Gerasimov (@karlicoss)" <karlicoss@gmail.com>
+License: The MIT License (MIT)
+        
+        Copyright (c) 2024 Dima Gerasimov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/karlicoss/dron
+Requires-Python: >=3.9
+License-File: LICENSE.txt
+Requires-Dist: click
+Requires-Dist: prompt_toolkit
+Requires-Dist: tzlocal
+Requires-Dist: textual
+Requires-Dist: tabulate
+Requires-Dist: termcolor
+Requires-Dist: mypy
+Requires-Dist: loguru
+Requires-Dist: dbus-python; platform_system != "Darwin"
+Provides-Extra: testing
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: ruff; extra == "testing"
+Requires-Dist: mypy; extra == "testing"
+Requires-Dist: lxml; extra == "testing"
+Provides-Extra: notify-telegram
+Requires-Dist: telegram-send>=0.37; extra == "notify-telegram"

dron-0.1.20241008/README.org

@@ -0,0 +1,135 @@
+#+begin_src python :results drawer :exports results 
+import dron; return dron.make_parser().description
+#+end_src
+
+#+RESULTS:
+:results:
+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
+:end:
+
+
+#+begin_src python :results drawer :exports results 
+import dron; return dron.make_parser().epilog
+#+end_src
+
+#+RESULTS:
+:results:
+
+* What does it do?
+In short, you type ~dron edit~ and edit your config file, similarly to ~crontab -e~:
+
+: 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',
+:     )
+
+
+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]]?
+
+:end:
+
+
+* Setting up
+
+1. install system dependencies (see =.ci/run= ) -- these are necessary for =dbus-python= library
+2. install dron: =pip3 install --user git+https://github.com/karlicoss/dron=
+3. install =sendmail= from your package manager if you want to recieve job failure emails
+
+* Using
+  
+#+begin_src python :results value :exports results 
+import dron; 
+p = dron.make_parser()
+p.prog = ''
+p.epilog = ''
+return p.format_help()
+#+end_src
+
+#+RESULTS:
+#+begin_example
+usage: [-h] [--marker MARKER] {monitor,past,edit,apply,lint,uninstall} ...
+
+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
+
+positional arguments:
+  {monitor,past,edit,apply,lint,uninstall}
+    monitor             Monitor services/timers managed by dron
+    past                List past job runs
+    edit                Edit  drontab (like 'crontab -e')
+    apply               Apply drontab (like 'crontab' with no args)
+    lint                Check drontab (no 'crontab' alternative, sadly!)
+    uninstall           Uninstall all managed jobs
+
+options:
+  -h, --help            show this help message and exit
+  --marker MARKER       Use custom marker instead of default `(MANAGED BY DRON)`. Possibly useful for developing/testing.
+#+end_example
+
+
+* Job syntax
+  
+The idea is that it's a simple python DSL that lets you define simple jobs with minimal friction.
+
+However, if you wish you can pass arbitrary unit properties as keyword arguments as well.
+
+* Caveats
+- older systemd versions would only accept absolute path for =ExecStart=. That should be caught during =dron edit= though
+  
+* Potential improvements
+- custom validation; at the moment it runs pylint, mypy and systemd verify
+- make it more atomic?
+
+  E.g. roll back all the changes until daemon-reload
+- more failure report mechanisms?
+
+  Ideally, benefit from [[https://github.com/dschep/ntfy][ntfy]]
+  
+** TODO add issues with various questions that I had in code?
+  

dron-0.1.20241008/conftest.py

@@ -0,0 +1,47 @@
+# this is a hack to monkey patch pytest so it handles tests inside namespace packages without __init__.py properly
+# without it, pytest can't discover the package root for some reason
+# also see https://github.com/karlicoss/pytest_namespace_pkgs for more
+
+import os
+import pathlib
+from typing import Optional
+
+import _pytest.main
+import _pytest.pathlib
+
+# we consider all dirs in repo/ to be namespace packages
+root_dir = pathlib.Path(__file__).absolute().parent.resolve() / 'src'
+assert root_dir.exists(), root_dir
+
+# TODO assert it contains package name?? maybe get it via setuptools..
+
+namespace_pkg_dirs = [str(d) for d in root_dir.iterdir() if d.is_dir()]
+
+# resolve_package_path is called from _pytest.pathlib.import_path
+# takes a full abs path to the test file and needs to return the path to the 'root' package on the filesystem
+resolve_pkg_path_orig = _pytest.pathlib.resolve_package_path
+def resolve_package_path(path: pathlib.Path) -> Optional[pathlib.Path]:
+    result = path  # search from the test file upwards
+    for parent in result.parents:
+        if str(parent) in namespace_pkg_dirs:
+            return parent
+    if os.name == 'nt':
+        # ??? for some reason on windows it is trying to call this against conftest? but not on linux/osx
+        if path.name == 'conftest.py':
+            return resolve_pkg_path_orig(path)
+    raise RuntimeError("Couldn't determine path for ", path)
+_pytest.pathlib.resolve_package_path = resolve_package_path
+
+
+# without patching, the orig function returns just a package name for some reason
+# (I think it's used as a sort of fallback)
+# so we need to point it at the absolute path properly
+# not sure what are the consequences.. maybe it wouldn't be able to run against installed packages? not sure..
+search_pypath_orig = _pytest.main.search_pypath
+def search_pypath(module_name: str) -> str:
+    mpath = root_dir / module_name.replace('.', os.sep)
+    if not mpath.is_dir():
+        mpath = mpath.with_suffix('.py')
+        assert mpath.exists(), mpath  # just in case
+    return str(mpath)
+_pytest.main.search_pypath = search_pypath

dron-0.1.20241008/mypy.ini

@@ -0,0 +1,14 @@
+[mypy]
+pretty = True
+show_error_context = True
+show_column_numbers = True
+show_error_end = True
+warn_redundant_casts = True
+warn_unused_ignores = True
+check_untyped_defs = True
+strict_equality = True
+enable_error_code = possibly-undefined
+
+# an example of suppressing
+# [mypy-my.config.repos.pdfannots.pdfannots]
+# ignore_errors = True

dron-0.1.20241008/pyproject.toml

@@ -0,0 +1,56 @@
+# see https://github.com/karlicoss/pymplate for up-to-date reference
+[project]
+dynamic = ["version"]  # version is managed by setuptools_scm
+name = "dron"
+dependencies = [
+    "click"         ,  # CLI
+    "prompt_toolkit",  # CLI
+    "tzlocal"       ,  # for monitor, to determine host timezone
+    "textual"       ,  # for 'new' monitor
+    "tabulate"      ,  # for 'old' monitor
+    "termcolor"     ,  # for 'old' monitor
+    "mypy"          ,  # for checking units
+    "loguru"        ,  # nicer logging
+    "dbus-python; platform_system != 'Darwin'",  # dbus interface to systemd
+]
+requires-python = ">=3.9"
+# FIXME dbus
+
+## these need to be set if you're planning to upload to pypi
+license = {file = "LICENSE.txt"}
+authors = [
+    {name = "Dima Gerasimov (@karlicoss)", email = "karlicoss@gmail.com"},
+]
+maintainers = [
+    {name = "Dima Gerasimov (@karlicoss)", email = "karlicoss@gmail.com"},
+]
+
+[project.urls]
+Homepage = "https://github.com/karlicoss/dron"
+##
+
+[project.scripts]
+dron = "dron.__main__:main"
+
+[project.optional-dependencies]
+testing = [
+    "pytest",
+    "ruff",
+    "mypy",
+    "lxml",  # for mypy html coverage
+]
+notify-telegram = [
+    # version before that had a bug that prevented it from working
+    # see https://github.com/rahiel/telegram-send/issues/115#issuecomment-1368728425
+    "telegram-send>=0.37",
+]
+
+
+[build-system]
+requires = ["setuptools", "setuptools-scm"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools_scm]
+version_scheme = "python-simplified-semver"
+local_scheme = "dirty-tag"
+

dron-0.1.20241008/pytest.ini

@@ -0,0 +1,13 @@
+[pytest]
+# discover files that don't follow test_ naming. Useful to keep tests along with the source code
+python_files = *.py
+addopts =
+  # -rap to print tests summary even when they are successful
+  -rap
+  --verbose
+
+  # otherwise it won't discover doctests
+  --doctest-modules
+
+  # show all test durations (unless they are too short)
+  --durations=0