summaryrefslogtreecommitdiffstats
path: root/scripts/external_libs/python-daemon-2.0.5/doc
diff options
context:
space:
mode:
Diffstat (limited to 'scripts/external_libs/python-daemon-2.0.5/doc')
-rw-r--r--scripts/external_libs/python-daemon-2.0.5/doc/CREDITS53
-rw-r--r--scripts/external_libs/python-daemon-2.0.5/doc/FAQ156
-rw-r--r--scripts/external_libs/python-daemon-2.0.5/doc/TODO95
-rw-r--r--scripts/external_libs/python-daemon-2.0.5/doc/hacking.txt180
4 files changed, 484 insertions, 0 deletions
diff --git a/scripts/external_libs/python-daemon-2.0.5/doc/CREDITS b/scripts/external_libs/python-daemon-2.0.5/doc/CREDITS
new file mode 100644
index 00000000..feb65d5e
--- /dev/null
+++ b/scripts/external_libs/python-daemon-2.0.5/doc/CREDITS
@@ -0,0 +1,53 @@
+Credits for contributors to ‘python-daemon’
+###########################################
+
+:Updated: 2014-12-23
+
+The ‘python-daemon’ library is the work of many contributors.
+
+
+Primary developers
+==================
+
+The library has been maintained over the years by:
+
+* Ben Finney <ben+python@benfinney.id.au>
+* Robert Niederreiter
+* Jens Klein
+
+
+Precursors
+==========
+
+The library code base is inherited from prior work by:
+
+* Chad J. Schroeder
+* Clark Evans
+* Noah Spurrier
+* Jürgen Hermann
+
+
+Additional contributors
+=======================
+
+People who have also contributed substantial improvements:
+
+
+
+..
+ 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/scripts/external_libs/python-daemon-2.0.5/doc/FAQ b/scripts/external_libs/python-daemon-2.0.5/doc/FAQ
new file mode 100644
index 00000000..1fcc4658
--- /dev/null
+++ b/scripts/external_libs/python-daemon-2.0.5/doc/FAQ
@@ -0,0 +1,156 @@
+‘python-daemon’ Frequently Asked Questions
+##########################################
+
+:Author: Ben Finney <ben+python@benfinney.id.au>
+:Updated: 2015-01-10
+
+.. 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 Security
+ 2.1 Why is the umask set to 0 by default?
+ 3 File descriptors
+ 3.1 Why does the output stop after opening the daemon context?
+ 3.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
+
+
+Security
+========
+
+Why is the umask set to 0 by default?
+-------------------------------------
+
+A daemon should not rely on the parent process's umask value, which is
+beyond its control and may prevent creating a file with the required
+access mode. So when the daemon context opens, the umask is set to an
+explicit known value.
+
+If the conventional value of 0 is too open, consider setting a value
+such as 0o022, 0o027, 0o077, or another specific value. Otherwise,
+ensure the daemon creates every file with an explicit access mode for
+the purpose.
+
+
+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/scripts/external_libs/python-daemon-2.0.5/doc/TODO b/scripts/external_libs/python-daemon-2.0.5/doc/TODO
new file mode 100644
index 00000000..81b41481
--- /dev/null
+++ b/scripts/external_libs/python-daemon-2.0.5/doc/TODO
@@ -0,0 +1,95 @@
+TODO for ‘python-daemon’ library
+################################
+
+:Updated: 2015-01-10
+
+=======
+PENDING
+=======
+
+Tests
+=====
+
+Libraries
+=========
+
+* 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
+==========================
+
+
+====
+DONE
+====
+
+* Convert to Python 2 and Python 3 compatible code base.
+
+* Work correctly with current ‘lockfile’ library (0.10 or later).
+
+* Write full unit tests for every new or changed behaviour at time of
+ commit.
+
+* 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: 0o000).
+
+* 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
+ 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/scripts/external_libs/python-daemon-2.0.5/doc/hacking.txt b/scripts/external_libs/python-daemon-2.0.5/doc/hacking.txt
new file mode 100644
index 00000000..9484dbd0
--- /dev/null
+++ b/scripts/external_libs/python-daemon-2.0.5/doc/hacking.txt
@@ -0,0 +1,180 @@
+Developer's guide
+#################
+
+:Author: Ben Finney <ben+python@benfinney.id.au>
+:Updated: 2014-11-28
+
+
+Project layout
+==============
+
+::
+
+ ./ Top level of source tree
+ doc/ Project documentation
+ bin/ Executable programs
+ daemon/ Main ‘daemon’ library
+ test/ Unit tests
+
+
+Code style
+==========
+
+Python
+------
+
+All Python code should conform to the guidelines in PEP8_. In
+particular:
+
+* Indent each level using 4 spaces (``U+0020 SPACE``), and no TABs
+ (``U+0008 CHARACTER TABULATION``).
+
+* Name modules in lower case, ``multiplewordslikethis``.
+
+* Name classes in title case, ``MultipleWordsLikeThis``.
+
+* Name functions, instances and other variables in lower case,
+ ``multiple_words_like_this``.
+
+* Every module, class, and function has a Python doc string explaining
+ its purpose and API.
+
+ *Exception*: Functions whose purpose and API are mandated by Python
+ itself (dunder-named methods) do not need a doc string.
+
+* Doc strings are written as triple-quoted strings.
+
+ * The text of the doc string is marked up with reStructuredText.
+
+ * The first line is a one-line synopsis of the object. This summary
+ line appears on the same line as the opening triple-quote,
+ separated by a single space.
+
+ * Further lines, if needed, are separated from the first by one
+ blank line.
+
+ * The synopsis is separated by one space from the opening
+ triple-quote; this causes it to appear four columns past the
+ beginning of the line. All subsequent lines are indented at least
+ four columns also.
+
+ * The synopsis is followed by a reStructuredText field list. The
+ field names are: “param foo” for each parameter (where “foo” is
+ the parameter name), and “return” for the return value. The field
+ values describe the purpose of each.
+
+ * The closing triple-quote appears on a separate line.
+
+ Example::
+
+ def frobnicate(spam, algorithm="dv"):
+ """ Perform frobnication on ``spam``.
+
+ :param spam: A travortionate (as a sequence of strings).
+ :param algorithm: The name of the algorithm to use for
+ frobnicating the travortionate.
+ :return: The frobnicated travortionate, if it is
+ non-empty; otherwise None.
+
+ The frobnication is done by the Dietzel-Venkman algorithm,
+ and optimises for the case where ``spam`` is freebled and
+ agglutinative.
+
+ """
+ spagnify(spam)
+ # …
+
+* All ``import`` statements appear at the top of the module.
+
+* Each ``import`` statement imports a single module, or multiple names
+ from a single module.
+
+ Example::
+
+ import sys
+ import os
+ from spam import foo, bar, baz
+
+.. _PEP8: http://www.python.org/dev/peps/pep-0008/
+
+Additional style guidelines:
+
+* All text files (including program code) are encoded in UTF-8.
+
+* A page break (``U+000C FORM FEED``) whitespace character is used
+ within a module to break up semantically separate areas of the
+ module.
+
+* Editor hints for Emacs and Vim appear in a comment block at the
+ file's end::
+
+
+ # Local variables:
+ # coding: utf-8
+ # mode: python
+ # End:
+ # vim: fileencoding=utf-8 filetype=python :
+
+
+Unit tests
+==========
+
+All code should aim for 100% coverage by unit tests. New code, or
+changes to existing code, will only be considered for inclusion in the
+development tree when accompanied by corresponding additions or
+changes to the unit tests.
+
+Test-driven development
+-----------------------
+
+Where possible, practice test-driven development to implement program
+code.
+
+* During a development session, maintain a separate window or terminal
+ with the unit test suite for the project running continuously, or
+ automatically every few seconds.
+
+* Any time a test is failing, the only valid change is to make all
+ tests pass.
+
+* Develop new interface features (changes to the program unit's
+ behaviour) only when all current tests pass.
+
+* Refactor as needed, but only when all tests pass.
+
+ * Refactoring is any change to the code which does not alter its
+ interface or expected behaviour, such as performance
+ optimisations, readability improvements, modularisation
+ improvements etc.
+
+* Develop new or changed program behaviour by:
+
+ * *First* write a single, specific test case for that new behaviour,
+ then watch the test fail in the absence of the desired behaviour.
+
+ * Implement the minimum necessary change to satisfy the failing
+ test. Continue until all tests pass again, then stop making
+ functional changes.
+
+ * Once all tests (including the new test) pass, consider refactoring
+ the code and the tests immediately, then ensure all the tests pass
+ again after any changes.
+
+ * Iterate for each incremental change in interface or behaviour.
+
+Test-driven development is not absolutely necessary, but is the
+simplest, most direct way to generate the kind of program changes
+accompanied by unit tests that are necessary for inclusion in the
+project.
+
+
+..
+ Local variables:
+ coding: utf-8
+ 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 :