#!/usr/bin/env python
from setuptools import setup
setup(
  name = 'cs.app.svcd',
  author = 'Cameron Simpson',
  author_email = 'cs@cskk.id.au',
  version = '20210316',
  url = 'https://bitbucket.org/cameron_simpson/css/commits/all',
  description =
    'SvcD class and "svcd" command to run persistent service programmes.',
  long_description =
    ('SvcD class and "svcd" command to run persistent service programmes.\n'    
 '\n'    
 '*Latest release 20210316*:\n'    
 'Serialise the Popen calls to avoid entirely hypothetical subprocess.Popen MT '    
 'bug that may be making portfwd coredump.\n'    
 '\n'    
 'This provides the features one wants from a daemon\n'    
 'for arbitrary commands providing a service:\n'    
 '\n'    
 '* process id (pid) files for both svcd and the service command\n'    
 '* filesystem visible status (command running, service enabled)\n'    
 '  via `cs.app.flag <https://pypi.org/project/cs.app.flag/>`_\n'    
 '* command restart if the command exits\n'    
 '* command control (stop, restart, disable)\n'    
 '  via `cs.app.flag <https://pypi.org/project/cs.app.flag/>`_\n'    
 '* test function to monitor for service viability;\n'    
 '  if the test function fails, do not run the service.\n'    
 '  This typically monitors something like\n'    
 '  network routing (suspend service while laptop offline)\n'    
 '  or a ping (suspend ssh tunnel while target does not answer pings).\n'    
 '* signature function to monitor for service restart;\n'    
 '  if the signature changes, restart the service.\n'    
 '  This typically monitors something like\n'    
 '  file contents (restart service on configuration change)\n'    
 '  or network routing (restart ssh tunnel on network change)\n'    
 '* callbacks for service command start and end,\n'    
 '  for example to display desktop notifications\n'    
 '\n'    
 'I use this to run persistent ssh port forwards\n'    
 'and a small collection of other personal services.\n'    
 'I have convenient shell commands to look up service status\n'    
 'and to start/stop/restart services.\n'    
 '\n'    
 'See `cs.app.portfwd <https://pypi.org/project/cs.app.portfwd/>`_\n'    
 'which I use to manage my ssh tunnels;\n'    
 'it is a single Python programme\n'    
 'running multiple ssh commands, each via its own SvcD instance.\n'    
 '\n'    
 '## Function `callproc(*a, **kw)`\n'    
 '\n'    
 'Workalike for subprocess.call, using LockedPopen.\n'    
 '\n'    
 '## Function `LockedPopen(*a, **kw)`\n'    
 '\n'    
 'Serialise the Popen calls.\n'    
 '\n'    
 'My long term multithreaded SvcD programmes sometimes coredump.\n'    
 'My working theory is that Popen, maybe only on MacOS, is\n'    
 'slightly not multithead safe. This function exists to test\n'    
 'that theory.\n'    
 '\n'    
 '## Function `main(argv=None)`\n'    
 '\n'    
 'Command line main programme.\n'    
 '\n'    
 '## Class `SvcD(cs.app.flag.FlaggedMixin)`\n'    
 '\n'    
 'A process based service.\n'    
 '\n'    
 '### Method `SvcD.__init__(self, argv, name=None, environ=None, flags=None, '    
 'group_name=None, pidfile=None, sig_func=None, test_flags=None, '    
 'test_func=None, test_rate=None, restart_delay=None, once=False, quiet=False, '    
 'trace=False, on_spawn=None, on_reap=None)`\n'    
 '\n'    
 'Initialise the SvcD.\n'    
 '\n'    
 'Parameters:\n'    
 '* `argv`: command to run as a subprocess.\n'    
 '* `flags`: a cs.app.flag.Flags -like object, default None;\n'    
 '  if None the default flags will be used.\n'    
 '* `group_name`: alert group name, default "SVCD " + `name`.\n'    
 '* `pidfile`: path to pid file, default $VARRUN/{name}.pid.\n'    
 '* `sig_func`: signature function to compute a string which\n'    
 '  causes a restart if it changes\n'    
 '* `test_flags`: map of {flagname: truthiness} which should\n'    
 '  be monitored at test time; truthy flags must be true and\n'    
 '  untruthy flags must be false\n'    
 '* `test_func`: test function with must return true if the comannd can run\n'    
 '* `test_rate`: frequency of tests, default TEST_RATE\n'    
 '* `restart_delay`: delay before start of an exiting command,\n'    
 '  default RESTART_DELAY\n'    
 '* `once`: if true, run the command only once\n'    
 '* `quiet`: if true, do not issue alerts\n'    
 '* `trace`: trace actions, default False\n'    
 '* `on_spawn`: to be called after a new subprocess is spawned\n'    
 '* `on_reap`: to be called after a subprocess is reaped\n'    
 '\n'    
 '### Method `SvcD.alert(self, msg, *a)`\n'    
 '\n'    
 'Issue an alert message via the "alert" command.\n'    
 '\n'    
 '### Method `SvcD.dbg(self, msg, *a)`\n'    
 '\n'    
 'Log a debug message if not tracing.\n'    
 '\n'    
 '### Method `SvcD.disable(self)`\n'    
 '\n'    
 'Turn on the disable flag.\n'    
 '\n'    
 '### Method `SvcD.enable(self)`\n'    
 '\n'    
 'Turn of the disable flag.\n'    
 '\n'    
 '### Method `SvcD.probe(self)`\n'    
 '\n'    
 'Probe the subprocess: true if running.\n'    
 '\n'    
 '### Method `SvcD.reap(self)`\n'    
 '\n'    
 'Collect the subprocess status after termination.\n'    
 '\n'    
 'Calls the `on_reap` function if any.\n'    
 '\n'    
 '### Method `SvcD.restart(self)`\n'    
 '\n'    
 'Set the restart flag, will be cleared by the restart.\n'    
 '\n'    
 '### Method `SvcD.spawn(self)`\n'    
 '\n'    
 'Spawn the subprocess.\n'    
 '\n'    
 'Calls the `on_spwan` function if any.\n'    
 '\n'    
 '### Method `SvcD.start(self)`\n'    
 '\n'    
 'Start the subprocess and its monitor.\n'    
 '\n'    
 '### Method `SvcD.stop(self)`\n'    
 '\n'    
 'Set the stop flag.\n'    
 '\n'    
 '### Method `SvcD.test(self)`\n'    
 '\n'    
 'Test whther the service should run.\n'    
 '\n'    
 'In order:\n'    
 '* `True` if the override flag is true.\n'    
 '* `False` if the disable flag is true.\n'    
 '* `False` if any of the specified test flags are false.\n'    
 '* `False` if the test function fails.\n'    
 '* Otherwise `True`.\n'    
 '\n'    
 '### Method `SvcD.wait(self)`\n'    
 '\n'    
 'Wait for the subprocess by waiting for the monitor.\n'    
 '\n'    
 '# Release Log\n'    
 '\n'    
 '\n'    
 '\n'    
 '*Release 20210316*:\n'    
 'Serialise the Popen calls to avoid entirely hypothetical subprocess.Popen MT '    
 'bug that may be making portfwd coredump.\n'    
 '\n'    
 '*Release 20190729*:\n'    
 'Get DEVNULL via cs.py3 instead of directly from subprocess.\n'    
 '\n'    
 '*Release 20190602.2*:\n'    
 'Another doc tweak.\n'    
 '\n'    
 '*Release 20190602.1*:\n'    
 'Improve module documentation formatting.\n'    
 '\n'    
 '*Release 20190602*:\n'    
 '* Support alert groups.\n'    
 '* Catch and report exceptions from the monitor signature function.\n'    
 '* Python 2 port fix for DEVNULL.\n'    
 '\n'    
 '*Release 20171118*:\n'    
 'Bugfix for su invocation in setuid mode. Improved signature command tracing '    
 'with -x option.\n'    
 '\n'    
 '*Release 20171026*:\n'    
 'Improved logic around signature changes.\n'    
 '\n'    
 '*Release 20171025*:\n'    
 'New "-F flag,..." option for svcd. Improve stop logic. Other small fixes.\n'    
 '\n'    
 '*Release 20170906*:\n'    
 'Initial PyPI release.'),
  classifiers = ['Programming Language :: Python', 'Programming Language :: Python :: 2', 'Programming Language :: Python :: 3', 'Topic :: Utilities', 'Development Status :: 4 - Beta', 'Intended Audience :: Developers', 'Operating System :: OS Independent', 'License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)'],
  entry_points = {'console_scripts': ['svcd = cs.app.svcd:main']},
  install_requires = ['cs.app.flag', 'cs.env', 'cs.logutils', 'cs.pfx', 'cs.psutils', 'cs.py3', 'cs.sh'],
  keywords = ['python2', 'python3'],
  license = 'GNU General Public License v3 or later (GPLv3+)',
  long_description_content_type = 'text/markdown',
  package_dir = {'': 'lib/python'},
  py_modules = ['cs.app.svcd'],
)
