PEP 3143: Resolve uses of the default role (#3383)
This commit is contained in:
Adam Turner
GitHub
parent
461e931fb5
commit
cc78d2150d
174
pep-3143.txt
174
pep-3143.txt
|
|
@ -38,7 +38,7 @@ Specification
|
|||
Example usage
|
||||
=============
|
||||
|
||||
Simple example of direct `DaemonContext` usage::
|
||||
Simple example of direct ``DaemonContext`` usage::
|
||||
|
||||
import daemon
|
||||
|
||||
|
|
@ -90,24 +90,24 @@ More complex example usage::
|
|||
Interface
|
||||
=========
|
||||
|
||||
A new package, `daemon`, is added to the standard library.
|
||||
A new package, ``daemon``, is added to the standard library.
|
||||
|
||||
A class, `DaemonContext`, is defined to represent the settings and
|
||||
A class, ``DaemonContext``, is defined to represent the settings and
|
||||
process context for the program running as a daemon process.
|
||||
|
||||
|
||||
``DaemonContext`` objects
|
||||
=========================
|
||||
|
||||
A `DaemonContext` instance represents the behaviour settings and
|
||||
A ``DaemonContext`` instance represents the behaviour settings and
|
||||
process context for the program when it becomes a daemon. The
|
||||
behaviour and environment is customised by setting options on the
|
||||
instance, before calling the `open` method.
|
||||
instance, before calling the ``open`` method.
|
||||
|
||||
Each option can be passed as a keyword argument to the `DaemonContext`
|
||||
Each option can be passed as a keyword argument to the ``DaemonContext``
|
||||
constructor, or subsequently altered by assigning to an attribute on
|
||||
the instance at any time prior to calling `open`. That is, for
|
||||
options named `wibble` and `wubble`, the following invocation::
|
||||
the instance at any time prior to calling ``open``. That is, for
|
||||
options named ``wibble`` and ``wubble``, the following invocation::
|
||||
|
||||
foo = daemon.DaemonContext(wibble=bar, wubble=baz)
|
||||
foo.open()
|
||||
|
|
@ -121,24 +121,24 @@ is equivalent to::
|
|||
|
||||
The following options are defined.
|
||||
|
||||
`files_preserve`
|
||||
``files_preserve``
|
||||
:Default: ``None``
|
||||
|
||||
List of files that should *not* be closed when starting the
|
||||
daemon. If ``None``, all open file descriptors will be closed.
|
||||
|
||||
Elements of the list are file descriptors (as returned by a file
|
||||
object's `fileno()` method) or Python `file` objects. Each
|
||||
object's ``fileno()`` method) or Python ``file`` objects. Each
|
||||
specifies a file that is not to be closed during daemon start.
|
||||
|
||||
`chroot_directory`
|
||||
``chroot_directory``
|
||||
:Default: ``None``
|
||||
|
||||
Full path to a directory to set as the effective root directory of
|
||||
the process. If ``None``, specifies that the root directory is not
|
||||
to be changed.
|
||||
|
||||
`working_directory`
|
||||
``working_directory``
|
||||
:Default: ``'/'``
|
||||
|
||||
Full path of the working directory to which the process should
|
||||
|
|
@ -149,7 +149,7 @@ The following options are defined.
|
|||
be left at default or set to a directory that is a sensible “home
|
||||
directory” for the daemon while it is running.
|
||||
|
||||
`umask`
|
||||
``umask``
|
||||
:Default: ``0``
|
||||
|
||||
File access creation mask (“umask”) to set for the process on
|
||||
|
|
@ -159,13 +159,13 @@ The following options are defined.
|
|||
starting the daemon will reset the umask to this value so that
|
||||
files are created by the daemon with access modes as it expects.
|
||||
|
||||
`pidfile`
|
||||
``pidfile``
|
||||
:Default: ``None``
|
||||
|
||||
Context manager for a PID lock file. When the daemon context opens
|
||||
and closes, it enters and exits the `pidfile` context manager.
|
||||
and closes, it enters and exits the ``pidfile`` context manager.
|
||||
|
||||
`detach_process`
|
||||
``detach_process``
|
||||
:Default: ``None``
|
||||
|
||||
If ``True``, detach the process context when opening the daemon
|
||||
|
|
@ -174,10 +174,10 @@ The following options are defined.
|
|||
If unspecified (``None``) during initialisation of the instance,
|
||||
this will be set to ``True`` by default, and ``False`` only if
|
||||
detaching the process is determined to be redundant; for example,
|
||||
in the case when the process was started by `init`, by `initd`, or
|
||||
by `inetd`.
|
||||
in the case when the process was started by ``init``, by ``initd``, or
|
||||
by ``inetd``.
|
||||
|
||||
`signal_map`
|
||||
``signal_map``
|
||||
:Default: system-dependent
|
||||
|
||||
Mapping from operating system signals to callback actions.
|
||||
|
|
@ -215,10 +215,10 @@ The following options are defined.
|
|||
on how to determine what circumstances dictate the need for signal
|
||||
handlers.
|
||||
|
||||
`uid`
|
||||
``uid``
|
||||
:Default: ``os.getuid()``
|
||||
|
||||
`gid`
|
||||
``gid``
|
||||
:Default: ``os.getgid()``
|
||||
|
||||
The user ID (“UID”) value and group ID (“GID”) value to switch
|
||||
|
|
@ -228,122 +228,122 @@ The following options are defined.
|
|||
relinquish any effective privilege elevation inherited by the
|
||||
process.
|
||||
|
||||
`prevent_core`
|
||||
``prevent_core``
|
||||
:Default: ``True``
|
||||
|
||||
If true, prevents the generation of core files, in order to avoid
|
||||
leaking sensitive information from daemons run as `root`.
|
||||
leaking sensitive information from daemons run as ``root``.
|
||||
|
||||
`stdin`
|
||||
``stdin``
|
||||
:Default: ``None``
|
||||
|
||||
`stdout`
|
||||
``stdout``
|
||||
:Default: ``None``
|
||||
|
||||
`stderr`
|
||||
``stderr``
|
||||
:Default: ``None``
|
||||
|
||||
Each of `stdin`, `stdout`, and `stderr` is a file-like object
|
||||
Each of ``stdin``, ``stdout``, and ``stderr`` is a file-like object
|
||||
which will be used as the new file for the standard I/O stream
|
||||
`sys.stdin`, `sys.stdout`, and `sys.stderr` respectively. The file
|
||||
``sys.stdin``, ``sys.stdout``, and ``sys.stderr`` respectively. The file
|
||||
should therefore be open, with a minimum of mode 'r' in the case
|
||||
of `stdin`, and mode 'w+' in the case of `stdout` and `stderr`.
|
||||
of ``stdin``, and mode 'w+' in the case of ``stdout`` and ``stderr``.
|
||||
|
||||
If the object has a `fileno()` method that returns a file
|
||||
If the object has a ``fileno()`` method that returns a file
|
||||
descriptor, the corresponding file will be excluded from being
|
||||
closed during daemon start (that is, it will be treated as though
|
||||
it were listed in `files_preserve`).
|
||||
it were listed in ``files_preserve``).
|
||||
|
||||
If ``None``, the corresponding system stream is re-bound to the
|
||||
file named by `os.devnull`.
|
||||
file named by ``os.devnull``.
|
||||
|
||||
|
||||
The following methods are defined.
|
||||
|
||||
`open()`
|
||||
``open()``
|
||||
:Return: ``None``
|
||||
|
||||
Open the daemon context, turning the current program into a daemon
|
||||
process. This performs the following steps:
|
||||
|
||||
* If this instance's `is_open` property is true, return
|
||||
immediately. This makes it safe to call `open` multiple times on
|
||||
* If this instance's ``is_open`` property is true, return
|
||||
immediately. This makes it safe to call ``open`` multiple times on
|
||||
an instance.
|
||||
|
||||
* If the `prevent_core` attribute is true, set the resource limits
|
||||
* If the ``prevent_core`` attribute is true, set the resource limits
|
||||
for the process to prevent any core dump from the process.
|
||||
|
||||
* If the `chroot_directory` attribute is not ``None``, set the
|
||||
* If the ``chroot_directory`` attribute is not ``None``, set the
|
||||
effective root directory of the process to that directory (via
|
||||
`os.chroot`).
|
||||
``os.chroot``).
|
||||
|
||||
This allows running the daemon process inside a “chroot gaol”
|
||||
as a means of limiting the system's exposure to rogue behaviour
|
||||
by the process. Note that the specified directory needs to
|
||||
already be set up for this purpose.
|
||||
|
||||
* Set the process UID and GID to the `uid` and `gid` attribute
|
||||
* Set the process UID and GID to the ``uid`` and ``gid`` attribute
|
||||
values.
|
||||
|
||||
* Close all open file descriptors. This excludes those listed in
|
||||
the `files_preserve` attribute, and those that correspond to the
|
||||
`stdin`, `stdout`, or `stderr` attributes.
|
||||
the ``files_preserve`` attribute, and those that correspond to the
|
||||
``stdin``, ``stdout``, or ``stderr`` attributes.
|
||||
|
||||
* Change current working directory to the path specified by the
|
||||
`working_directory` attribute.
|
||||
``working_directory`` attribute.
|
||||
|
||||
* Reset the file access creation mask to the value specified by
|
||||
the `umask` attribute.
|
||||
the ``umask`` attribute.
|
||||
|
||||
* If the `detach_process` option is true, detach the current
|
||||
* If the ``detach_process`` option is true, detach the current
|
||||
process into its own process group, and disassociate from any
|
||||
controlling terminal.
|
||||
|
||||
* Set signal handlers as specified by the `signal_map` attribute.
|
||||
* Set signal handlers as specified by the ``signal_map`` attribute.
|
||||
|
||||
* If any of the attributes `stdin`, `stdout`, `stderr` are not
|
||||
``None``, bind the system streams `sys.stdin`, `sys.stdout`,
|
||||
and/or `sys.stderr` to the files represented by the
|
||||
* If any of the attributes ``stdin``, ``stdout``, ``stderr`` are not
|
||||
``None``, bind the system streams ``sys.stdin``, ``sys.stdout``,
|
||||
and/or ``sys.stderr`` to the files represented by the
|
||||
corresponding attributes. Where the attribute has a file
|
||||
descriptor, the descriptor is duplicated (instead of re-binding
|
||||
the name).
|
||||
|
||||
* If the `pidfile` attribute is not ``None``, enter its context
|
||||
* If the ``pidfile`` attribute is not ``None``, enter its context
|
||||
manager.
|
||||
|
||||
* Mark this instance as open (for the purpose of future `open` and
|
||||
`close` calls).
|
||||
* Mark this instance as open (for the purpose of future ``open`` and
|
||||
``close`` calls).
|
||||
|
||||
* Register the `close` method to be called during Python's exit
|
||||
* Register the ``close`` method to be called during Python's exit
|
||||
processing.
|
||||
|
||||
When the function returns, the running program is a daemon
|
||||
process.
|
||||
|
||||
`close()`
|
||||
``close()``
|
||||
:Return: ``None``
|
||||
|
||||
Close the daemon context. This performs the following steps:
|
||||
|
||||
* If this instance's `is_open` property is false, return
|
||||
immediately. This makes it safe to call `close` multiple times
|
||||
* If this instance's ``is_open`` property is false, return
|
||||
immediately. This makes it safe to call ``close`` multiple times
|
||||
on an instance.
|
||||
|
||||
* If the `pidfile` attribute is not ``None``, exit its context
|
||||
* If the ``pidfile`` attribute is not ``None``, exit its context
|
||||
manager.
|
||||
|
||||
* Mark this instance as closed (for the purpose of future `open`
|
||||
and `close` calls).
|
||||
* Mark this instance as closed (for the purpose of future ``open``
|
||||
and ``close`` calls).
|
||||
|
||||
`is_open`
|
||||
``is_open``
|
||||
:Return: ``True`` if the instance is open, ``False`` otherwise.
|
||||
|
||||
This property exposes the state indicating whether the instance is
|
||||
currently open. It is ``True`` if the instance's `open` method has
|
||||
been called and the `close` method has not subsequently been
|
||||
currently open. It is ``True`` if the instance's ``open`` method has
|
||||
been called and the ``close`` method has not subsequently been
|
||||
called.
|
||||
|
||||
`terminate(signal_number, stack_frame)`
|
||||
``terminate(signal_number, stack_frame)``
|
||||
:Return: ``None``
|
||||
|
||||
Signal handler for the ``signal.SIGTERM`` signal. Performs the
|
||||
|
|
@ -354,16 +354,16 @@ The following methods are defined.
|
|||
The class also implements the context manager protocol via
|
||||
``__enter__`` and ``__exit__`` methods.
|
||||
|
||||
`__enter__()`
|
||||
``__enter__()``
|
||||
:Return: The ``DaemonContext`` instance
|
||||
|
||||
Call the instance's `open()` method, then return the instance.
|
||||
Call the instance's ``open()`` method, then return the instance.
|
||||
|
||||
`__exit__(exc_type, exc_value, exc_traceback)`
|
||||
``__exit__(exc_type, exc_value, exc_traceback)``
|
||||
:Return: ``True`` or ``False`` as defined by the context manager
|
||||
protocol
|
||||
|
||||
Call the instance's `close()` method, then return ``True`` if the
|
||||
Call the instance's ``close()`` method, then return ``True`` if the
|
||||
exception was handled or ``False`` if it was not.
|
||||
|
||||
|
||||
|
|
@ -409,13 +409,13 @@ following steps to become a Unix daemon process.
|
|||
|
||||
* Correctly handle the following circumstances:
|
||||
|
||||
* Started by System V `init` process.
|
||||
* Started by System V ``init`` process.
|
||||
|
||||
* Daemon termination by ``SIGTERM`` signal.
|
||||
|
||||
* Children generate ``SIGCLD`` signal.
|
||||
|
||||
The `daemon` tool [slack-daemon]_ lists (in its summary of features)
|
||||
The ``daemon`` tool [slack-daemon]_ lists (in its summary of features)
|
||||
behaviour that should be performed when turning a program into a
|
||||
well-behaved Unix daemon process. It differs from this PEP's intent in
|
||||
that it invokes a *separate* program as a daemon process. The
|
||||
|
|
@ -424,7 +424,7 @@ once the program is already running:
|
|||
|
||||
* Sets up the correct process context for a daemon.
|
||||
|
||||
* Behaves sensibly when started by `initd(8)` or `inetd(8)`.
|
||||
* Behaves sensibly when started by ``initd(8)`` or ``inetd(8)``.
|
||||
|
||||
* Revokes any suid or sgid privileges to reduce security risks in case
|
||||
daemon is incorrectly installed with special privileges.
|
||||
|
|
@ -468,7 +468,7 @@ a service.
|
|||
Reference Implementation
|
||||
========================
|
||||
|
||||
The `python-daemon` package [python-daemon]_.
|
||||
The ``python-daemon`` package [python-daemon]_.
|
||||
|
||||
Other daemon implementations
|
||||
============================
|
||||
|
|
@ -482,23 +482,23 @@ following implementations:
|
|||
* Many good ideas were contributed by the community to Python cookbook
|
||||
recipes #66012 [cookbook-66012]_ and #278731 [cookbook-278731]_.
|
||||
|
||||
* The `bda.daemon` library [bda.daemon]_ is an implementation of
|
||||
* The ``bda.daemon`` library [bda.daemon]_ is an implementation of
|
||||
[cookbook-66012]_. It is the predecessor of [python-daemon]_.
|
||||
|
||||
Other Python daemon implementations that differ from this PEP:
|
||||
|
||||
* The `zdaemon` tool [zdaemon]_ was written for the Zope project. Like
|
||||
* The ``zdaemon`` tool [zdaemon]_ was written for the Zope project. Like
|
||||
[slack-daemon]_, it differs from this specification because it is
|
||||
used to run another program as a daemon process.
|
||||
|
||||
* The Python library `daemon` [clapper-daemon]_ is (according to its
|
||||
* The Python library ``daemon`` [clapper-daemon]_ is (according to its
|
||||
homepage) no longer maintained. As of version 1.0.1, it implements
|
||||
the basic steps from [stevens]_.
|
||||
|
||||
* The `daemonize` library [seutter-daemonize]_ also implements the
|
||||
* The ``daemonize`` library [seutter-daemonize]_ also implements the
|
||||
basic steps from [stevens]_.
|
||||
|
||||
* Ray Burr's `daemon.py` module [burr-daemon]_ provides the [stevens]_
|
||||
* Ray Burr's ``daemon.py`` module [burr-daemon]_ provides the [stevens]_
|
||||
procedure as well as PID file handling and redirection of output to
|
||||
syslog.
|
||||
|
||||
|
|
@ -507,8 +507,8 @@ Other Python daemon implementations that differ from this PEP:
|
|||
with the rest of the Twisted framework; it differs significantly
|
||||
from the API in this PEP.
|
||||
|
||||
* The Python `initd` library [dagitses-initd]_, which uses
|
||||
[clapper-daemon]_, implements an equivalent of Unix `initd(8)` for
|
||||
* The Python ``initd`` library [dagitses-initd]_, which uses
|
||||
[clapper-daemon]_, implements an equivalent of Unix ``initd(8)`` for
|
||||
controlling a daemon process.
|
||||
|
||||
|
||||
|
|
@ -518,17 +518,17 @@ References
|
|||
|
||||
.. [stevens]
|
||||
|
||||
`Unix Network Programming`, W. Richard Stevens, 1994 Prentice
|
||||
``Unix Network Programming``, W. Richard Stevens, 1994 Prentice
|
||||
Hall.
|
||||
|
||||
.. [slack-daemon]
|
||||
|
||||
The (non-Python) “libslack” implementation of a `daemon` tool
|
||||
The (non-Python) “libslack” implementation of a ``daemon`` tool
|
||||
`<http://www.libslack.org/daemon/>`_ by “raf” <raf@raf.org>.
|
||||
|
||||
.. [python-daemon]
|
||||
|
||||
The `python-daemon` library
|
||||
The ``python-daemon`` library
|
||||
`<http://pypi.python.org/pypi/python-daemon/>`_ by Ben Finney et
|
||||
al.
|
||||
|
||||
|
|
@ -544,39 +544,39 @@ References
|
|||
|
||||
.. [bda.daemon]
|
||||
|
||||
The `bda.daemon` library
|
||||
The ``bda.daemon`` library
|
||||
`<http://pypi.python.org/pypi/bda.daemon/>`_ by Robert
|
||||
Niederreiter et al.
|
||||
|
||||
.. [zdaemon]
|
||||
|
||||
The `zdaemon` tool `<http://pypi.python.org/pypi/zdaemon/>`_ by
|
||||
The ``zdaemon`` tool `<http://pypi.python.org/pypi/zdaemon/>`_ by
|
||||
Guido van Rossum et al.
|
||||
|
||||
.. [clapper-daemon]
|
||||
|
||||
The `daemon` library `<http://pypi.python.org/pypi/daemon/>`_ by
|
||||
The ``daemon`` library `<http://pypi.python.org/pypi/daemon/>`_ by
|
||||
Brian Clapper.
|
||||
|
||||
.. [seutter-daemonize]
|
||||
|
||||
The `daemonize` library `<http://daemonize.sourceforge.net/>`_ by
|
||||
The ``daemonize`` library `<http://daemonize.sourceforge.net/>`_ by
|
||||
Jerry Seutter.
|
||||
|
||||
.. [burr-daemon]
|
||||
|
||||
The `daemon.py` module
|
||||
The ``daemon.py`` module
|
||||
`<http://www.nightmare.com/~ryb/code/daemon.py>`_ by Ray Burr.
|
||||
|
||||
.. [twisted]
|
||||
|
||||
The `Twisted` application framework
|
||||
The ``Twisted`` application framework
|
||||
`<http://pypi.python.org/pypi/Twisted/>`_ by Glyph Lefkowitz et
|
||||
al.
|
||||
|
||||
.. [dagitses-initd]
|
||||
|
||||
The Python `initd` library `<http://pypi.python.org/pypi/initd/>`_
|
||||
The Python ``initd`` library `<http://pypi.python.org/pypi/initd/>`_
|
||||
by Michael Andreas Dagitses.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue