[Zodb-checkins] SVN: zdaemon/trunk/s Used manuel to make the documentation more documenty
jim
cvs-admin at zope.org
Fri May 25 21:43:39 UTC 2012
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()
-"""
More information about the Zodb-checkins
mailing list