Log message for revision 126502: Used manuel to make the documentation more documenty
Changed: U zdaemon/trunk/setup.py U zdaemon/trunk/src/zdaemon/README.txt U zdaemon/trunk/src/zdaemon/tests/tests.py -=- Modified: zdaemon/trunk/setup.py =================================================================== --- zdaemon/trunk/setup.py 2012-05-25 20:28:10 UTC (rev 126501) +++ zdaemon/trunk/setup.py 2012-05-25 21:43:35 UTC (rev 126502) @@ -29,7 +29,8 @@ entry_points=entry_points, include_package_data = True, install_requires=["ZConfig"], - extras_require=dict(test=['zope.testing']), + extras_require=dict( + test=['zope.testing', 'manuel', 'zc.customdoctests']), ) except ImportError: from distutils.core import setup @@ -48,10 +49,10 @@ long_description=( read('README.txt') + '\n' + + read('src/zdaemon/README.txt') + + '\n' + read('CHANGES.txt') + '\n' + - read('src/zdaemon/README.txt') - + '\n' + '========\n' + 'Download\n' + '========\n' Modified: zdaemon/trunk/src/zdaemon/README.txt =================================================================== --- zdaemon/trunk/src/zdaemon/README.txt 2012-05-25 20:28:10 UTC (rev 126501) +++ zdaemon/trunk/src/zdaemon/README.txt 2012-05-25 21:43:35 UTC (rev 126502) @@ -2,9 +2,9 @@ Using zdaemon =============== -zdaemon provides a script, zdaemon, that can be used to running other +zdaemon provides a script, zdaemon, that can be used to run other programs as POSIX (Unix) daemons. (Of course, it is only usable on -POSIX-complient systems. +POSIX-complient systems.) Using zdaemon requires specifying a number of options, which can be given in a configuration file, or as command-line options. It also @@ -42,10 +42,11 @@ Let's start with a simple example. We'll use command-line options to run the echo command: - >>> system("./zdaemon -p 'echo hello world' fg") + sh> ./zdaemon -p 'echo hello world' fg echo hello world hello world + Here we used the -p option to specify a program to run. We can specify a program name and command-line options in the program command. Note, however, that the command-line parsing is pretty @@ -53,44 +54,45 @@ a slightly more complex example. We'll run the sleep command as a daemon :) - >>> system("./zdaemon -p 'sleep 100' start") + sh> ./zdaemon -p 'sleep 100' start . . daemon process started, pid=819 This ran the sleep deamon. We can check whether it ran with the status command: - >>> system("./zdaemon -p 'sleep 100' status") + sh> ./zdaemon -p 'sleep 100' status program running; pid=819 We can stop it with the stop command: - >>> system("./zdaemon -p 'sleep 100' stop") + sh> ./zdaemon -p 'sleep 100' stop . . daemon process stopped - >>> system("./zdaemon -p 'sleep 100' status") + sh> ./zdaemon -p 'sleep 100' status daemon manager not running Normally, we control zdaemon using a configuration file. Let's create -a typical configuration file: +a typical configuration file:: - >>> open('conf', 'w').write( - ... ''' - ... <runner> - ... program sleep 100 - ... </runner> - ... ''') + <runner> + program sleep 100 + </runner> +.. -> text + + >>> open('conf', 'w').write(text) + Now, we can run with the -C option to read the configuration file: - >>> system("./zdaemon -Cconf start") + sh> ./zdaemon -Cconf start . . daemon process started, pid=1136 If we list the directory: - >>> system("ls") + sh> ls conf zdaemon zdsock @@ -99,54 +101,65 @@ socket used internally by ZDaemon. We'll normally want to control where this goes. - >>> system("./zdaemon -Cconf stop") + sh> ./zdaemon -Cconf stop . . daemon process stopped - >>> open('conf', 'w').write( - ... ''' - ... <runner> - ... program sleep 100 - ... socket-name /tmp/demo.zdsock - ... </runner> - ... '''.replace('/tmp', tmpdir)) +Here's an updated configuration:: + <runner> + program sleep 100 + socket-name /tmp/demo.zdsock + </runner> - >>> system("./zdaemon -Cconf start") +.. -> text + + >>> open('conf', 'w').write(text.replace('/tmp', tmpdir)) + +Now, when we run zdaemon: + + sh> ./zdaemon -Cconf start . . daemon process started, pid=1139 - >>> system("ls") + sh> ls conf zdaemon +.. test + >>> import os >>> os.path.exists("/tmp/demo.zdsock".replace('/tmp', tmpdir)) True - >>> system("./zdaemon -Cconf stop") +The socket file is created in the given directory. + + sh> ./zdaemon -Cconf stop . . daemon process stopped In the example, we included a command-line argument in the program -option. We can also provide options on the command line: +option. We can also provide options on the command line:: - >>> open('conf', 'w').write( - ... ''' - ... <runner> - ... program sleep - ... socket-name /tmp/demo.zdsock - ... </runner> - ... '''.replace('/tmp', tmpdir)) + <runner> + program sleep + socket-name /tmp/demo.zdsock + </runner> - >>> system("./zdaemon -Cconf start 100") +.. -> text + + >>> open('conf', 'w').write(text.replace('/tmp', tmpdir)) + +Then we can pass the program argument on the command line: + + sh> ./zdaemon -Cconf start 100 . . daemon process started, pid=1149 - >>> system("./zdaemon -Cconf status") + sh> ./zdaemon -Cconf status program running; pid=1149 - >>> system("./zdaemon -Cconf stop") + sh> ./zdaemon -Cconf stop . . daemon process stopped @@ -157,19 +170,24 @@ a program. Perhaps the most common case for this is setting LD_LIBRARY_PATH so that dynamically loaded libraries can be found. - >>> open('conf', 'w').write( - ... ''' - ... <runner> - ... program env - ... socket-name /tmp/demo.zdsock - ... </runner> - ... <environment> - ... LD_LIBRARY_PATH /home/foo/lib - ... HOME /home/foo - ... </environment> - ... '''.replace('/tmp', tmpdir)) +:: - >>> system("./zdaemon -Cconf fg") + <runner> + program env + socket-name /tmp/demo.zdsock + </runner> + <environment> + LD_LIBRARY_PATH /home/foo/lib + HOME /home/foo + </environment> + +.. -> text + + >>> open('conf', 'w').write(text.replace('/tmp', tmpdir)) + +Now, when we run the command, we'll see out environment settings reflected: + + sh> ./zdaemon -Cconf fg env USER=jim HOME=/home/foo @@ -200,15 +218,20 @@ >>> import os >>> f.write('rec 1\n'); os.fsync(f.fileno()) - >>> open('conf', 'w').write( - ... ''' - ... <runner> - ... program tail -f data - ... transcript log - ... </runner> - ... ''') +Now, here's out zdaemon configuration:: - >>> system("./zdaemon -Cconf start") + <runner> + program tail -f data + transcript log + </runner> + +.. -> text + + >>> open('conf', 'w').write(text) + +Now we'll start: + + sh> ./zdaemon -Cconf start . . daemon process started, pid=7963 @@ -217,7 +240,7 @@ >>> import time >>> time.sleep(0.1) -Now, if we look at the log file, it contains the tail output: +After waiting a bit, if we look at the log file, it contains the tail output: >>> open('log').read() 'rec 1\n' @@ -244,7 +267,7 @@ Now, if we tell zdaemon to reopen the file: - >>> system("./zdaemon -Cconf reopen_transcript") + sh> ./zdaemon -Cconf reopen_transcript and generate some output: Modified: zdaemon/trunk/src/zdaemon/tests/tests.py =================================================================== --- zdaemon/trunk/src/zdaemon/tests/tests.py 2012-05-25 20:28:10 UTC (rev 126501) +++ zdaemon/trunk/src/zdaemon/tests/tests.py 2012-05-25 21:43:35 UTC (rev 126502) @@ -13,6 +13,9 @@ ############################################################################## import doctest +import manuel.capture +import manuel.doctest +import manuel.testing import os import re import shutil @@ -21,6 +24,7 @@ import tempfile import unittest import ZConfig +import zc.customdoctests import zdaemon from zope.testing import renormalizing @@ -137,7 +141,27 @@ match.sort() return '\n'.join(match) + '\n' +zdaemon_template = """#!%(python)s + +import sys +sys.path[0:0] = [ + %(zdaemon)r, + %(ZConfig)r, + ] + +import zdaemon.zdctl + +if __name__ == '__main__': + zdaemon.zdctl.main() +""" + def test_suite(): + README_checker = renormalizing.RENormalizing([ + (re.compile('pid=\d+'), 'pid=NNN'), + (re.compile('(\. )+\.?'), '<BLANKLINE>'), + (re.compile('^env\n((?:.*\n)+)$'), checkenv), + ]) + return unittest.TestSuite(( doctest.DocTestSuite( setUp=setUp, tearDown=tearDown, @@ -146,28 +170,18 @@ (re.compile('(\. )+\.?'), '<BLANKLINE>'), ]) ), - doctest.DocFileSuite( + manuel.testing.TestSuite( + manuel.doctest.Manuel( + parser=zc.customdoctests.DocTestParser( + ps1='sh>', + transform=lambda s: 'system("%s")\n' % s.rstrip() + ), + checker=README_checker, + ) + + manuel.doctest.Manuel(checker=README_checker) + + manuel.capture.Manuel(), '../README.txt', setUp=setUp, tearDown=tearDown, - checker=renormalizing.RENormalizing([ - (re.compile('pid=\d+'), 'pid=NNN'), - (re.compile('(\. )+\.?'), '<BLANKLINE>'), - (re.compile('^env\n((?:.*\n)+)$'), checkenv), - ]) - ), + ), )) - -zdaemon_template = """#!%(python)s - -import sys -sys.path[0:0] = [ - %(zdaemon)r, - %(ZConfig)r, - ] - -import zdaemon.zdctl - -if __name__ == '__main__': - zdaemon.zdctl.main() -""" _______________________________________________ Zope-Checkins maillist - Zope-Checkins@zope.org https://mail.zope.org/mailman/listinfo/zope-checkins