diff options
Diffstat (limited to 'external_libs/python/python-daemon-2.0.5/doc')
| -rw-r--r-- | external_libs/python/python-daemon-2.0.5/doc/CREDITS | 53 | ||||
| -rw-r--r-- | external_libs/python/python-daemon-2.0.5/doc/FAQ | 156 | ||||
| -rw-r--r-- | external_libs/python/python-daemon-2.0.5/doc/TODO | 95 | ||||
| -rw-r--r-- | external_libs/python/python-daemon-2.0.5/doc/hacking.txt | 180 |
4 files changed, 0 insertions, 484 deletions
diff --git a/external_libs/python/python-daemon-2.0.5/doc/CREDITS b/external_libs/python/python-daemon-2.0.5/doc/CREDITS deleted file mode 100644 index feb65d5e..00000000 --- a/external_libs/python/python-daemon-2.0.5/doc/CREDITS +++ /dev/null @@ -1,53 +0,0 @@ -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/external_libs/python/python-daemon-2.0.5/doc/FAQ b/external_libs/python/python-daemon-2.0.5/doc/FAQ deleted file mode 100644 index 1fcc4658..00000000 --- a/external_libs/python/python-daemon-2.0.5/doc/FAQ +++ /dev/null @@ -1,156 +0,0 @@ -‘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/external_libs/python/python-daemon-2.0.5/doc/TODO b/external_libs/python/python-daemon-2.0.5/doc/TODO deleted file mode 100644 index 81b41481..00000000 --- a/external_libs/python/python-daemon-2.0.5/doc/TODO +++ /dev/null @@ -1,95 +0,0 @@ -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/external_libs/python/python-daemon-2.0.5/doc/hacking.txt b/external_libs/python/python-daemon-2.0.5/doc/hacking.txt deleted file mode 100644 index 9484dbd0..00000000 --- a/external_libs/python/python-daemon-2.0.5/doc/hacking.txt +++ /dev/null @@ -1,180 +0,0 @@ -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 : |