From 0ab5fdc6595043efc78adb1dfe4653c51d53652d Mon Sep 17 00:00:00 2001 From: Fedor Gogolev Date: Mon, 2 Nov 2015 18:03:12 +0300 Subject: [PATCH] Add sphinx-doc, migrate to rst in readme Fixed #14, #26 --- .gitignore | 1 + MANIFEST.in | 5 +- README.md | 56 ----------- README.rst | 80 +++++++++++++++ daemonize.py | 48 +++++---- docs/conf.py | 266 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 14 +++ setup.py | 11 +- 8 files changed, 402 insertions(+), 79 deletions(-) delete mode 100644 README.md create mode 100644 README.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.gitignore b/.gitignore index b4197fc..30f7a00 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,7 @@ *.pyc .ropeproject __pycache__ +docs/_build build daemonize.egg-info dist diff --git a/MANIFEST.in b/MANIFEST.in index 3760f73..e257b53 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,6 @@ include MANIFEST.in -include README.md +include README.rst include LICENSE + +graft docs +recursive-exclude docs *.pyc *.pyo \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 1e24a46..0000000 --- a/README.md +++ /dev/null @@ -1,56 +0,0 @@ -# daemonize [![Build Status](https://secure.travis-ci.org/thesharp/daemonize.png)](http://travis-ci.org/thesharp/daemonize) - -## Description -**daemonize** is a library for writing system daemons in Python. It has some bits from [daemonize.sourceforge.net](http://daemonize.sourceforge.net). It is distributed under MIT license. - -## Dependencies -It is tested under following Python versions: - -- 2.6 -- 2.7 -- 3.3 - - -## Installation -You can install it from Python Package Index (PyPI): - - $ pip install daemonize - -## Usage -```python -from time import sleep -from daemonize import Daemonize - -pid = "/tmp/test.pid" - - -def main(): - while True: - sleep(5) - -daemon = Daemonize(app="test_app", pid=pid, action=main) -daemon.start() -``` - -## File descriptors -Daemonize object's constructor understands the optional argument **keep_fds** which contains a list of FDs which should not be closed. For example: -```python -import logging -from daemonize import Daemonize - -pid = "/tmp/test.pid" -logger = logging.getLogger(__name__) -logger.setLevel(logging.DEBUG) -logger.propagate = False -fh = logging.FileHandler("/tmp/test.log", "w") -fh.setLevel(logging.DEBUG) -logger.addHandler(fh) -keep_fds = [fh.stream.fileno()] - - -def main(): - logger.debug("Test") - -daemon = Daemonize(app="test_app", pid=pid, action=main, keep_fds=keep_fds) -daemon.start() -``` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..0396b21 --- /dev/null +++ b/README.rst @@ -0,0 +1,80 @@ +daemonize |Build Status| +======================== + +**daemonize** is a library for writing system daemons in Python. It has +some bits from +`daemonize.sourceforge.net `__. It is +distributed under MIT license. + +Dependencies +------------ + +It is tested under following Python versions: + +- 2.6 +- 2.7 +- 3.3 + +Installation +------------ + +You can install it from Python Package Index (PyPI): + +:: + + $ pip install daemonize + +Usage +----- + +.. code:: python + + from time import sleep + from daemonize import Daemonize + + pid = "/tmp/test.pid" + + + def main(): + while True: + sleep(5) + + daemon = Daemonize(app="test_app", pid=pid, action=main) + daemon.start() + +File descriptors +---------------- + +Daemonize object's constructor understands the optional argument +**keep\_fds** which contains a list of FDs which should not be closed. +For example: + +.. code:: python + + import logging + from daemonize import Daemonize + + pid = "/tmp/test.pid" + logger = logging.getLogger(__name__) + logger.setLevel(logging.DEBUG) + logger.propagate = False + fh = logging.FileHandler("/tmp/test.log", "w") + fh.setLevel(logging.DEBUG) + logger.addHandler(fh) + keep_fds = [fh.stream.fileno()] + + + def main(): + logger.debug("Test") + + daemon = Daemonize(app="test_app", pid=pid, action=main, keep_fds=keep_fds) + daemon.start() + +API +--- + +.. automodule:: daemonize + :members: + +.. |Build Status| image:: https://secure.travis-ci.org/thesharp/daemonize.png + :target: http://travis-ci.org/thesharp/daemonize diff --git a/daemonize.py b/daemonize.py index f0ecc63..5d0ddff 100644 --- a/daemonize.py +++ b/daemonize.py @@ -12,24 +12,30 @@ import atexit from logging import handlers +__version__ = "2.3.1" + + class Daemonize(object): - """ Daemonize object - Object constructor expects three arguments: - - app: contains the application name which will be sent to syslog. - - pid: path to the pidfile. - - action: your custom function which will be executed after daemonization. - - keep_fds: optional list of fds which should not be closed. - - auto_close_fds: optional parameter to not close opened fds. - - privileged_action: action that will be executed before drop privileges if user or - group parameter is provided. - If you want to transfer anything from privileged_action to action, such as - opened privileged file descriptor, you should return it from - privileged_action function and catch it inside action function. - - user: drop privileges to this user if provided. - - group: drop privileges to this group if provided. - - verbose: send debug messages to logger if provided. - - logger: use this logger object instead of creating new one, if provided. - - foreground: stay in foreground; do not fork (for debugging) + """ + Daemonize object. + + Object constructor expects three arguments. + + :param app: contains the application name which will be sent to syslog. + :param pid: path to the pidfile. + :param action: your custom function which will be executed after daemonization. + :param keep_fds: optional list of fds which should not be closed. + :param auto_close_fds: optional parameter to not close opened fds. + :param privileged_action: action that will be executed before drop privileges if user or + group parameter is provided. + If you want to transfer anything from privileged_action to action, such as + opened privileged file descriptor, you should return it from + privileged_action function and catch it inside action function. + :param user: drop privileges to this user if provided. + :param group: drop privileges to this group if provided. + :param verbose: send debug messages to logger if provided. + :param logger: use this logger object instead of creating new one, if provided. + :param foreground: stay in foreground; do not fork (for debugging) """ def __init__(self, app, pid, action, keep_fds=None, auto_close_fds=True, privileged_action=None, user=None, group=None, verbose=False, logger=None, foreground=False): self.app = app @@ -45,7 +51,7 @@ class Daemonize(object): self.foreground = foreground def sigterm(self, signum, frame): - """ sigterm method + """ These actions will be done after SIGTERM. """ self.logger.warn("Caught signal %s. Stopping daemon." % signum) @@ -53,7 +59,7 @@ class Daemonize(object): sys.exit(0) def exit(self): - """ exit method + """ Cleanup pid file at exit. """ self.logger.warn("Stopping daemon.") @@ -61,8 +67,8 @@ class Daemonize(object): sys.exit(0) def start(self): - """ start method - Main daemonization process. + """ + Start daemonization process. """ # If pidfile already exists, we should read pid from there; to overwrite it, if locking # will fail, because locking attempt somehow purges the file contents. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0a04ee8 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,266 @@ +# -*- coding: utf-8 -*- +# +# daemonize documentation build configuration file, created by +# sphinx-quickstart on Mon Nov 2 17:36:41 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.viewcode', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'daemonize' +copyright = u'2015, Ilya Otyutskiy' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. + +from daemonize import __version__ + +version = __version__ +release = __version__ +# The full version, including alpha/beta/rc tags. + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +import sphinx_rtd_theme + +html_theme = "sphinx_rtd_theme" + +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'daemonizedoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + ('index', 'daemonize.tex', u'daemonize Documentation', + u'Ilya Otyutskiy', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'daemonize', u'daemonize Documentation', + [u'Ilya Otyutskiy'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'daemonize', u'daemonize Documentation', + u'Ilya Otyutskiy', 'daemonize', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..642532b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,14 @@ +.. daemonize documentation master file, created by + sphinx-quickstart on Mon Nov 2 17:36:41 2015. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +.. include:: ../README.rst + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/setup.py b/setup.py index f05fe37..44a7c89 100644 --- a/setup.py +++ b/setup.py @@ -1,10 +1,19 @@ #!/usr/bin/python +import re + from setuptools import setup, find_packages +_version_re = re.compile(r'__version__\s+=\s+(.*)') + + +with open('daemonize.py', 'rb') as f: + version = str(ast.literal_eval(_version_re.search( + f.read().decode('utf-8')).group(1))) + setup( name="daemonize", - version="2.3.1", + version=version, py_modules=["daemonize"], author="Ilya Otyutskiy", author_email="ilya.otyutskiy@icloud.com",