Imported from /home/lorry/working-area/delta_python-packages_python-daemon/python-daemon-1.6.1.tar.gz.HEADpython-daemon-1.6.1master

2 files changed, 232 insertions, 0 deletions

diff --git a/doc/FAQ b/doc/FAQ
new file mode 100644
index 0000000..c8148c4
--- /dev/null
+++ b/doc/FAQ
@@ -0,0 +1,143 @@
+‘python-daemon’ Frequently Asked Questions
+##########################################
+
+:Author: Ben Finney <ben+python@benfinney.id.au>
+:Updated: 2014-05-21
+
+..
+    This is free software: you may copy, modify, and/or distribute this work
+    under the terms of the Apache License version 2.0 as published by the
+    Apache Software Foundation.
+    No warranty expressed or implied. See the file LICENSE.ASF-2 for details.
+
+..  contents::
+..
+    1  General
+      1.1  What is the purpose of the ‘python-daemon’ library?
+      1.2  How can I run a service communicating with a separate daemon process?
+    2  File descriptors
+      2.1  Why does the output stop after opening the daemon context?
+      2.2  How can I preserve a ‘logging’ handler's file descriptor?
+
+General
+=======
+
+What is the purpose of the ‘python-daemon’ library?
+---------------------------------------------------
+
+The ‘python-daemon’ library has a deliberately narrow focus: that of
+being a reference implementation for `PEP 3143`_, “Standard daemon
+process library”.
+
+..  _`PEP 3143`: http://www.python.org/dev/peps/pep-3143
+
+How can I run a service communicating with a separate daemon process?
+---------------------------------------------------------------------
+
+As specified in `PEP 3143`_, the ‘python-daemon’ library is
+specifically focussed on the goal of having the *current running
+program* become a well-behaved Unix daemon process. This leaves open
+the question of how this program is started, or about multiple
+programs interacting. As detailed in PEP 3143:
+
+    A daemon is not a service
+
+    There is a related concept in many systems, called a “service”. A
+    service differs from the model in this PEP, in that rather than
+    having the *current* program continue to run as a daemon process,
+    a service starts an *additional* process to run in the background,
+    and the current process communicates with that additional process
+    via some defined channels.
+
+    The Unix-style daemon model in this PEP can be used, among other
+    things, to implement the background-process part of a service; but
+    this PEP does not address the other aspects of setting up and
+    managing a service.
+
+A possible starting point for such a “service” model of execution is
+in a `message from 2009-01-30`_ to the ``python-ideas`` forum.
+
+..  _`message from 2009-01-30`: http://mail.python.org/pipermail/python-ideas/2009-January/002606.html
+
+
+File descriptors
+================
+
+Why does the output stop after opening the daemon context?
+----------------------------------------------------------
+
+The specified behaviour in `PEP 3143`_ includes the requirement to
+detach the process from the controlling terminal (to allow the process
+to continue to run as a daemon), and to close all file descriptors not
+known to be safe once detached (to ensure any files that continue to
+be used are under the control of the daemon process).
+
+If you want the process to generate output via the system streams
+‘sys.stdout’ and ‘sys.stderr’, set the ‘DaemonContext’'s ‘stdout’
+and/or ‘stderr’ options to a file-like object (e.g. the ‘stream’
+attribute of a ‘logging.Handler’ instance). If these objects have file
+descriptors, they will be preserved when the daemon context opens.
+
+How can I preserve a ‘logging’ handler's file descriptor?
+---------------------------------------------------------
+
+The ‘DaemonContext.open’ method conforms to `PEP 3143`_ by closing all
+open file descriptors, but excluding those files specified in the
+‘files_preserve’ option. This option is a list of files or file
+descriptors.
+
+The Python standard library ‘logging’ module provides log handlers
+that write to streams, including to files via the ‘StreamHandler’
+class and its sub-classes. The documentation (both the online `logging
+module documentation`_ and the docstrings for the code) makes no
+mention of a way to get at the stream associated with a handler
+object.
+
+However, looking at the source code for ‘StreamHandler’, in Python 2.5
+as ``/usr/lib/python2.5/logging/__init__.py``, shows a ‘stream’
+attribute that is bound to the stream object. The attribute is not
+marked private (i.e. it is not named with a leading underscore), so we
+can presume it is part of the public API.
+
+That attribute can then be used to specify that a logging handler's
+file descriptor should, when the ‘DaemonContext’ opens, be excluded
+from closure::
+
+    import logging
+    import daemon
+
+    # any subclass of StreamHandler should provide the ‘stream’ attribute.
+    lh = logging.handlers.TimedRotatingFileHandler(
+            "/var/log/foo.log",
+            # …
+            )
+
+    # … do some logging and other activity …
+
+    daemon_context = daemon.DaemonContext()
+    daemon_context.files_preserve = [lh.stream]
+
+    daemon_context.open()
+
+    # … continue as a daemon process …
+
+..  _`logging module documentation`: http://docs.python.org/library/logging
+
+
+..
+    This is free software: you may copy, modify, and/or distribute this work
+    under the terms of the Apache License version 2.0 as published by the
+    Apache Software Foundation.
+    No warranty expressed or implied. See the file LICENSE.ASF-2 for details.
+
+..
+    Local variables:
+    coding: utf-8
+    mode: text
+    mode: rst
+    time-stamp-format: "%:y-%02m-%02d"
+    time-stamp-start: "^:Updated:[         ]+"
+    time-stamp-end: "$"
+    time-stamp-line-limit: 20
+    End:
+    vim: fileencoding=utf-8 filetype=rst :
diff --git a/doc/TODO b/doc/TODO
new file mode 100644
index 0000000..94a1e72
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,89 @@
+TODO for ‘python-daemon’ library
+################################
+
+=======
+PENDING
+=======
+
+Tests
+=====
+
+* Write full unit tests for every new or changed behaviour at time of
+  commit.
+
+Libraries
+=========
+
+* Work correctly with current ‘lockfile’ library (0.9 or later).
+
+* Evaluate switching to ‘flufl.lock’ library for PID lockfile behaviour
+  <http://pypi.python.org/pypi/flufl.lock>_.
+
+Features
+========
+
+Important
+---------
+
+Wishlist
+--------
+
+* Allow specification of a syslog service name to log as (default:
+  output to stdout and stderr, not syslog).
+
+Documentation
+=============
+
+Standard library inclusion
+==========================
+
+* Convert to Python 3.
+
+
+====
+DONE
+====
+
+* Detect whether started by another process that handles
+  daemonisation, such as ‘inetd’, and behave appropriately.
+
+* Detach to new process and session group.
+
+* Allow specification of working directory (default: '/').
+
+* Allow specification of umask (default: 0000).
+
+* Drop ‘suid’ and ‘sgid’ privileges if set.
+
+* Close all open file handles.
+
+* Re-open stdin, stdout, stderr to user-specified files.
+
+* Default re-open stdin, stdout, stderr to ‘/dev/null’.
+
+* Allow specification of a non-root user and group to drop to, if
+  started as ‘root’ (default: no change of user or group).
+
+* Implement context manager protocol for daemon context.
+
+* Allow specification of PID file with its own context manager
+  (default: no PID file).
+
+* Full docstrings for functions, classes, and modules.
+
+* PEP 3143 for adding this library to the Python standard library.
+
+
+..
+    This is free software: you may copy, modify, and/or distribute this work
+    under the terms of the Apache License version 2.0 as published by the
+    Apache Software Foundation.
+    No warranty expressed or implied. See the file LICENSE.ASF-2 for details.
+
+..
+    Local variables:
+    coding: utf-8
+    mode: text
+    mode: rst
+    End:
+    vim: fileencoding=utf-8 filetype=rst :