diff options
| author | Giampaolo Rodola <g.rodola@gmail.com> | 2018-01-01 22:04:16 +0100 |
|---|---|---|
| committer | Giampaolo Rodola <g.rodola@gmail.com> | 2018-01-01 22:04:16 +0100 |
| commit | 9806c4801cba4c239425226d9db8c5a7f8beb902 (patch) | |
| tree | 3e7feba9e15c9f08ecfdf4d9714d8dd37311d576 /docs | |
| parent | c604a55694cc70d54f7abea628d41d99842944cc (diff) | |
| parent | a86c6f65c123442802c44d27e45b5e014a62fe3b (diff) | |
| download | psutil-1102-proc-bitness.tar.gz | |
merge from master1102-proc-bitness
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile | 57 | ||||
| -rw-r--r-- | docs/README | 4 | ||||
| -rw-r--r-- | docs/_static/css/custom.css | 518 | ||||
| -rw-r--r-- | docs/_template/globaltoc.html | 12 | ||||
| -rw-r--r-- | docs/_template/indexcontent.html | 4 | ||||
| -rw-r--r-- | docs/_template/indexsidebar.html | 8 | ||||
| -rw-r--r-- | docs/_template/page.html | 66 | ||||
| -rw-r--r-- | docs/_themes/pydoctheme/static/pydoctheme.css | 197 | ||||
| -rw-r--r-- | docs/_themes/pydoctheme/theme.conf | 23 | ||||
| -rw-r--r-- | docs/conf.py | 235 | ||||
| -rw-r--r-- | docs/index.rst | 302 |
11 files changed, 937 insertions, 489 deletions
diff --git a/docs/Makefile b/docs/Makefile index a69fc329..0c4bdf48 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -15,8 +15,7 @@ ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . # the i18n builder cannot share the environment and doctrees with the others I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - +.PHONY: help help: @echo "Please use \`make <target>' where <target> is one of" @echo " html to make standalone HTML files" @@ -26,8 +25,10 @@ help: @echo " json to make JSON files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" @echo " devhelp to make HTML files and a Devhelp project" @echo " epub to make an epub" + @echo " epub3 to make an epub3" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @echo " latexpdf to make LaTeX files and run them through pdflatex" @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" @@ -41,41 +42,51 @@ help: @echo " pseudoxml to make pseudoxml-XML files for display purposes" @echo " linkcheck to check all external links for integrity" @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" +.PHONY: clean clean: rm -rf $(BUILDDIR) +.PHONY: html html: $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." +.PHONY: dirhtml dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." +.PHONY: singlehtml singlehtml: $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml @echo @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." +.PHONY: pickle pickle: $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle @echo @echo "Build finished; now you can process the pickle files." +.PHONY: json json: $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json @echo @echo "Build finished; now you can process the JSON files." +.PHONY: htmlhelp htmlhelp: $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp @echo @echo "Build finished; now you can run HTML Help Workshop with the" \ ".hhp project file in $(BUILDDIR)/htmlhelp." +.PHONY: qthelp qthelp: $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp @echo @@ -85,6 +96,16 @@ qthelp: @echo "To view the help file:" @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/psutil.qhc" +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp devhelp: $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp @echo @@ -94,11 +115,19 @@ devhelp: @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/psutil" @echo "# devhelp" +.PHONY: epub epub: $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub @echo @echo "Build finished. The epub file is in $(BUILDDIR)/epub." +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex latex: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo @@ -106,28 +135,33 @@ latex: @echo "Run \`make' in that directory to run these through (pdf)latex" \ "(use \`make latexpdf' here to do that automatically)." +.PHONY: latexpdf latexpdf: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through pdflatex..." $(MAKE) -C $(BUILDDIR)/latex all-pdf @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." +.PHONY: latexpdfja latexpdfja: $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex @echo "Running LaTeX files through platex and dvipdfmx..." $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." +.PHONY: text text: $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text @echo @echo "Build finished. The text files are in $(BUILDDIR)/text." +.PHONY: man man: $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man @echo @echo "Build finished. The manual pages are in $(BUILDDIR)/man." +.PHONY: texinfo texinfo: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo @@ -135,39 +169,58 @@ texinfo: @echo "Run \`make' in that directory to run these through makeinfo" \ "(use \`make info' here to do that automatically)." +.PHONY: info info: $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo @echo "Running Texinfo files through makeinfo..." make -C $(BUILDDIR)/texinfo info @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." +.PHONY: gettext gettext: $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale @echo @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." +.PHONY: changes changes: $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes @echo @echo "The overview file is in $(BUILDDIR)/changes." +.PHONY: linkcheck linkcheck: $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck @echo @echo "Link check complete; look for any errors in the above output " \ "or in $(BUILDDIR)/linkcheck/output.txt." +.PHONY: doctest doctest: $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest @echo "Testing of doctests in the sources finished, look at the " \ "results in $(BUILDDIR)/doctest/output.txt." +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml xml: $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml @echo @echo "Build finished. The XML files are in $(BUILDDIR)/xml." +.PHONY: pseudoxml pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/README b/docs/README index 3aaea8a5..8ceb5f21 100644 --- a/docs/README +++ b/docs/README @@ -3,7 +3,7 @@ About This directory contains the reStructuredText (reST) sources to the psutil documentation. You don't need to build them yourself, prebuilt versions are -available at https://pythonhosted.org/psutil/. +available at http://psutil.readthedocs.io. In case you want, you need to install sphinx first: $ pip install sphinx @@ -12,4 +12,4 @@ Then run: $ make html -You'll then have an HTML version of the doc at _build/html/index.html.
\ No newline at end of file +You'll then have an HTML version of the doc at _build/html/index.html. diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 00000000..b76f442a --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,518 @@ +.wy-nav-content { + max-width: 100% !important; + padding: 15px !important; +} + +.rst-content dl:not(.docutils) { + margin: 0px 0px 0px 0px; +} + +.data dd { + margin-bottom: 0px !important; +} + +.data .descname { + border-right:10px !important; +} + +.local-toc li ul li{ + padding-left: 20px !important; +} + +.function .descclassname { + font-weight: normal !important; +} + +.class .descclassname { + font-weight: normal !important; +} + +.admonition.warning { + padding-top: 2px !important; + padding-bottom: 2px !important; +} + +.admonition.note { + padding-top: 2px !important; + padding-bottom: 2px !important; +} + +.rst-content dl:not(.docutils) dt { + color: #555; +} + +.sig-paren { + padding-left: 2px; + padding-right: 2px; +} + +h1, h2, h3 { + background: #eee; + padding: 5px; + border-bottom: 1px solid #ccc; +} + +h1 { + font-size: 35px; +} + +.admonition.warning { + padding-top: 5px !important; + padding-bottom: 5px !important; +} + +.admonition.warning p { + margin-bottom: 5px !important; +} + +.admonition.note { + padding-top: 5px !important; + padding-bottom: 5px !important; +} + +.admonition.note p { + margin-bottom: 5px !important; + backround-color: rgb(238, 255, 204) !important; +} + +.codeblock div[class^='highlight'], pre.literal-block div[class^='highlight'], .rst-content .literal-block div[class^='highlight'], div[class^='highlight'] div[class^='highlight'] { + background-color: #eeffcc !important; +} + +.highlight .hll { + background-color: #ffffcc +} + +.highlight { + background: #eeffcc; +} + +.highlight-default, .highlight-python { + border-radius: 3px !important; + border: 1px solid #ac9 !important; +} + +.highlight .c { + color: #408090; + font-style: italic +} + +.wy-side-nav-search { + background-color: grey !important +} + +.highlight { + border-radius: 3px !important; + +} + +div.highlight-default { + margin-bottom: 10px !important; +} + +pre { + padding: 5px !important; +} + +/* ================================================================== */ +/* Warnings and info boxes like python doc */ +/* ================================================================== */ + +div.admonition { + margin-top: 10px !important; + margin-bottom: 10px !important; +} + +div.warning { + background-color: #ffe4e4 !important; + border: 1px solid #f66 !important; + border-radius: 3px !important; +} + +div.note { + background-color: #eee !important; + border: 1px solid #ccc !important; + border-radius: 3px !important; +} + +div.admonition p.admonition-title + p { + display: inline !important; +} + +p.admonition-title { + display: inline !important; + background: none !important; + color: black !important; +} + +p.admonition-title:after { + content: ":" !important; +} + +div.body div.admonition, div.body div.impl-detail { +} + +.fa-exclamation-circle:before, .wy-inline-validate.wy-inline-validate-warning .wy-input-context:before, .wy-inline-validate.wy-inline-validate-info .wy-input-context:before, .rst-content .admonition-title:before { + display: none !important; +} + +.note code { + background: #d6d6d6 !important; +} + +/* ================================================================== */ +/* Syntax highlight like Python doc. +/* ================================================================== */ + +/* Comment */ +.highlight .err { + border: 1px solid #FF0000 +} + +/* Error */ +.highlight .k { + color: #007020; + font-weight: bold +} + +/* Keyword */ +.highlight .o { + color: #666666 +} + +/* Operator */ +.highlight .ch { + color: #408090; + font-style: italic +} + +/* Comment.Hashbang */ +.highlight .cm { + color: #408090; + font-style: italic +} + +/* Comment.Multiline */ +.highlight .cp { + color: #007020 +} + +/* Comment.Preproc */ +.highlight .cpf { + color: #408090; + font-style: italic +} + +/* Comment.PreprocFile */ +.highlight .c1 { + color: #408090; + font-style: italic +} + +/* Comment.Single */ +.highlight .cs { + color: #408090; + background-color: #fff0f0 +} + +/* Comment.Special */ +.highlight .gd { + color: #A00000 +} + +/* Generic.Deleted */ +.highlight .ge { + font-style: italic +} + +/* Generic.Emph */ +.highlight .gr { + color: #FF0000 +} + +/* Generic.Error */ +.highlight .gh { + color: #000080; + font-weight: bold +} + +/* Generic.Heading */ +.highlight .gi { + color: #00A000 +} + +/* Generic.Inserted */ +.highlight .go { + color: #333333 +} + +/* Generic.Output */ +.highlight .gp { + color: #c65d09; + font-weight: bold +} + +/* Generic.Prompt */ +.highlight .gs { + font-weight: bold +} + +/* Generic.Strong */ +.highlight .gu { + color: #800080; + font-weight: bold +} + +/* Generic.Subheading */ +.highlight .gt { + color: #0044DD +} + +/* Generic.Traceback */ +.highlight .kc { + color: #007020; + font-weight: bold +} + +/* Keyword.Constant */ +.highlight .kd { + color: #007020; + font-weight: bold +} + +/* Keyword.Declaration */ +.highlight .kn { + color: #007020; + font-weight: bold +} + +/* Keyword.Namespace */ +.highlight .kp { + color: #007020 +} + +/* Keyword.Pseudo */ +.highlight .kr { + color: #007020; + font-weight: bold +} + +/* Keyword.Reserved */ +.highlight .kt { + color: #902000 +} + +/* Keyword.Type */ +.highlight .m { + color: #208050 +} + +/* Literal.Number */ +.highlight .s { + color: #4070a0 +} + +/* Literal.String */ +.highlight .na { + color: #4070a0 +} + +/* Name.Attribute */ +.highlight .nb { + color: #007020 +} + +/* Name.Builtin */ +.highlight .nc { + color: #0e84b5; + font-weight: bold +} + +/* Name.Class */ +.highlight .no { + color: #60add5 +} + +/* Name.Constant */ +.highlight .nd { + color: #555555; + font-weight: bold +} + +/* Name.Decorator */ +.highlight .ni { + color: #d55537; + font-weight: bold +} + +/* Name.Entity */ +.highlight .ne { + color: #007020 +} + +/* Name.Exception */ +.highlight .nf { + color: #06287e +} + +/* Name.Function */ +.highlight .nl { + color: #002070; + font-weight: bold +} + +/* Name.Label */ +.highlight .nn { + color: #0e84b5; + font-weight: bold +} + +/* Name.Namespace */ +.highlight .nt { + color: #062873; + font-weight: bold +} + +/* Name.Tag */ +.highlight .nv { + color: #bb60d5 +} + +/* Name.Variable */ +.highlight .ow { + color: #007020; + font-weight: bold +} + +/* Operator.Word */ +.highlight .w { + color: #bbbbbb +} + +/* Text.Whitespace */ +.highlight .mb { + color: #208050 +} + +/* Literal.Number.Bin */ +.highlight .mf { + color: #208050 +} + +/* Literal.Number.Float */ +.highlight .mh { + color: #208050 +} + +/* Literal.Number.Hex */ +.highlight .mi { + color: #208050 +} + +/* Literal.Number.Integer */ +.highlight .mo { + color: #208050 +} + +/* Literal.Number.Oct */ +.highlight .sa { + color: #4070a0 +} + +/* Literal.String.Affix */ +.highlight .sb { + color: #4070a0 +} + +/* Literal.String.Backtick */ +.highlight .sc { + color: #4070a0 +} + +/* Literal.String.Char */ +.highlight .dl { + color: #4070a0 +} + +/* Literal.String.Delimiter */ +.highlight .sd { + color: #4070a0; + font-style: italic +} + +/* Literal.String.Doc */ +.highlight .s2 { + color: #4070a0 +} + +/* Literal.String.Double */ +.highlight .se { + color: #4070a0; + font-weight: bold +} + +/* Literal.String.Escape */ +.highlight .sh { + color: #4070a0 +} + +/* Literal.String.Heredoc */ +.highlight .si { + color: #70a0d0; + font-style: italic +} + +/* Literal.String.Interpol */ +.highlight .sx { + color: #c65d09 +} + +/* Literal.String.Other */ +.highlight .sr { + color: #235388 +} + +/* Literal.String.Regex */ +.highlight .s1 { + color: #4070a0 +} + +/* Literal.String.Single */ +.highlight .ss { + color: #517918 +} + +/* Literal.String.Symbol */ +.highlight .bp { + color: #007020 +} + +/* Name.Builtin.Pseudo */ +.highlight .fm { + color: #06287e +} + +/* Name.Function.Magic */ +.highlight .vc { + color: #bb60d5 +} + +/* Name.Variable.Class */ +.highlight .vg { + color: #bb60d5 +} + +/* Name.Variable.Global */ +.highlight .vi { + color: #bb60d5 +} + +/* Name.Variable.Instance */ +.highlight .vm { + color: #bb60d5 +} + +/* Name.Variable.Magic */ +.highlight .il { + color: #208050 +} diff --git a/docs/_template/globaltoc.html b/docs/_template/globaltoc.html deleted file mode 100644 index f5fbb406..00000000 --- a/docs/_template/globaltoc.html +++ /dev/null @@ -1,12 +0,0 @@ -{# - basic/globaltoc.html - ~~~~~~~~~~~~~~~~~~~~ - - Sphinx sidebar template: global table of contents. - - :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -#} -<h3>{{ _('Manual') }}</h3> -{{ toctree() }} -<a href="{{ pathto(master_doc) }}">Back to Welcome</a> diff --git a/docs/_template/indexcontent.html b/docs/_template/indexcontent.html deleted file mode 100644 index dd5e7249..00000000 --- a/docs/_template/indexcontent.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "defindex.html" %} -{% block tables %} - -{% endblock %} diff --git a/docs/_template/indexsidebar.html b/docs/_template/indexsidebar.html deleted file mode 100644 index 903675d1..00000000 --- a/docs/_template/indexsidebar.html +++ /dev/null @@ -1,8 +0,0 @@ -<h3>Useful links</h3> -<ul> - <li><a href="https://github.com/giampaolo/psutil">Github project</a></li> - <li><a href="http://grodola.blogspot.com/search/label/psutil">Blog</a></li> - <li><a href="https://pypi.python.org/pypi?:action=display&name=psutil#downloads">Download</a></li> - <li><a href="https://github.com/giampaolo/psutil/issues">Issues</a></li> - <li><a href="http://groups.google.com/group/psutil/topics">Forum</a></li> -</ul> diff --git a/docs/_template/page.html b/docs/_template/page.html deleted file mode 100644 index 04b47b41..00000000 --- a/docs/_template/page.html +++ /dev/null @@ -1,66 +0,0 @@ -{% extends "!page.html" %} -{% block extrahead %} -{{ super() }} -{% if not embedded %}<script type="text/javascript" src="{{ pathto('_static/copybutton.js', 1) }}"></script>{% endif %} -<script type="text/javascript"> - - // Store editor pop-up help state in localStorage - // so it does not re-pop-up itself between page loads. - // Do not even to pretend to support IE gracefully. - (function($) { - - $(document).ready(function() { - var box = $("#editor-trap"); - var klass = "toggled"; - var storageKey = "toggled"; - - function toggle() { - box.toggleClass(klass); - // Store the toggle status in local storage as "has value string" or null - window.localStorage.setItem(storageKey, box.hasClass(klass) ? "toggled" : "not-toggled"); - } - - box.click(toggle); - - // Check the persistent state of the editor pop-up - // Note that localStorage does not necessarily support boolean values (ugh!) - // http://stackoverflow.com/questions/3263161/cannot-set-boolean-values-in-localstorage - var v = window.localStorage.getItem(storageKey); - if(v == "toggled" || !v) { - box.addClass(klass); - } - - }); - - })(jQuery); -</script> -<script type="text/javascript"> - - var _gaq = _gaq || []; - _gaq.push(['_setAccount', 'UA-2097050-4']); - _gaq.push(['_trackPageview']); - - (function() { - var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; - ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; - var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); - })(); - -</script> -{% endblock %} - -{% block rootrellink %} - <li><a href="https://github.com/giampaolo/psutil/"><img src="{{ pathto('_static/logo.png', 1) }}" style="height: 30px; vertical-align: middle; padding-right: 1em;" /> Project Homepage</a>{{ reldelim1 }}</li> - <li><a href="{{ pathto('index') }}">{{ shorttitle }}</a>{{ reldelim1 }}</li> -{% endblock %} - - -{% block footer %} -<div class="footer"> - © Copyright {{ copyright|e }}. - <br /> - Last updated on {{ last_updated|e }}. - <br /> - Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> {{ sphinx_version|e }}. -</div> -{% endblock %}
\ No newline at end of file diff --git a/docs/_themes/pydoctheme/static/pydoctheme.css b/docs/_themes/pydoctheme/static/pydoctheme.css deleted file mode 100644 index c6f19ab7..00000000 --- a/docs/_themes/pydoctheme/static/pydoctheme.css +++ /dev/null @@ -1,197 +0,0 @@ -@import url("default.css"); - -body { - background-color: white; - margin-left: 1em; - margin-right: 1em; -} - -div.related { - margin-bottom: 1.2em; - padding: 0.5em 0; - border-top: 1px solid #ccc; - margin-top: 0.5em; -} - -div.related a:hover { - color: #0095C4; -} - -div.related:first-child { - border-top: 0; - padding-top: 0; - border-bottom: 1px solid #ccc; -} - -div.sphinxsidebar { - background-color: #eeeeee; - border-radius: 5px; - line-height: 130%; - font-size: smaller; -} - -div.sphinxsidebar h3, div.sphinxsidebar h4 { - margin-top: 1.5em; -} - -div.sphinxsidebarwrapper > h3:first-child { - margin-top: 0.2em; -} - -div.sphinxsidebarwrapper > ul > li > ul > li { - margin-bottom: 0.4em; -} - -div.sphinxsidebar a:hover { - color: #0095C4; -} - -div.sphinxsidebar input { - font-family: 'Lucida Grande','Lucida Sans','DejaVu Sans',Arial,sans-serif; - border: 1px solid #999999; - font-size: smaller; - border-radius: 3px; -} - -div.sphinxsidebar input[type=text] { - max-width: 150px; -} - -div.body { - padding: 0 0 0 1.2em; -} - -div.body p { - line-height: 140%; -} - -div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 { - margin: 0; - border: 0; - padding: 0.3em 0; -} - -div.body hr { - border: 0; - background-color: #ccc; - height: 1px; -} - -div.body pre { - border-radius: 3px; - border: 1px solid #ac9; -} - -div.body div.admonition, div.body div.impl-detail { - border-radius: 3px; -} - -div.body div.impl-detail > p { - margin: 0; -} - -div.body div.seealso { - border: 1px solid #dddd66; -} - -div.body a { - color: #00608f; -} - -div.body a:visited { - color: #30306f; -} - -div.body a:hover { - color: #00B0E4; -} - -tt, pre { - font-family: monospace, sans-serif; - font-size: 96.5%; -} - -div.body tt { - border-radius: 3px; -} - -div.body tt.descname { - font-size: 120%; -} - -div.body tt.xref, div.body a tt { - font-weight: normal; -} - -p.deprecated { - border-radius: 3px; -} - -table.docutils { - border: 1px solid #ddd; - min-width: 20%; - border-radius: 3px; - margin-top: 10px; - margin-bottom: 10px; -} - -table.docutils td, table.docutils th { - border: 1px solid #ddd !important; - border-radius: 3px; -} - -table p, table li { - text-align: left !important; -} - -table.docutils th { - background-color: #eee; - padding: 0.3em 0.5em; -} - -table.docutils td { - background-color: white; - padding: 0.3em 0.5em; -} - -table.footnote, table.footnote td { - border: 0 !important; -} - -div.footer { - line-height: 150%; - margin-top: -2em; - text-align: right; - width: auto; - margin-right: 10px; -} - -div.footer a:hover { - color: #0095C4; -} - -div.body h1, -div.body h2, -div.body h3 { - background-color: #EAEAEA; - border-bottom: 1px solid #CCC; - padding-top: 2px; - padding-bottom: 2px; - padding-left: 5px; - margin-top: 5px; - margin-bottom: 5px; -} - -div.body h2 { - padding-left:10px; -} - -.data { - margin-top: 4px !important; - margin-bottom: 4px !important; -} - -.data dd { - margin-top: 0px !important; - margin-bottom: 0px !important; -} diff --git a/docs/_themes/pydoctheme/theme.conf b/docs/_themes/pydoctheme/theme.conf deleted file mode 100644 index 95b97e53..00000000 --- a/docs/_themes/pydoctheme/theme.conf +++ /dev/null @@ -1,23 +0,0 @@ -[theme] -inherit = default -stylesheet = pydoctheme.css -pygments_style = sphinx - -[options] -bodyfont = 'Lucida Grande', 'Lucida Sans', 'DejaVu Sans', Arial, sans-serif -headfont = 'Lucida Grande', 'Lucida Sans', 'DejaVu Sans', Arial, sans-serif -footerbgcolor = white -footertextcolor = #555555 -relbarbgcolor = white -relbartextcolor = #666666 -relbarlinkcolor = #444444 -sidebarbgcolor = white -sidebartextcolor = #444444 -sidebarlinkcolor = #444444 -bgcolor = white -textcolor = #222222 -linkcolor = #0090c0 -visitedlinkcolor = #00608f -headtextcolor = #1a1a1a -headbgcolor = white -headlinkcolor = #aaaaaa diff --git a/docs/conf.py b/docs/conf.py index f0a206db..df825cbd 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # # psutil documentation build configuration file, created by -# sphinx-quickstart. +# sphinx-quickstart on Wed Oct 19 21:54:30 2016. # # This file is execfile()d with the current directory set to its # containing dir. @@ -12,12 +12,22 @@ # All configuration values have a default; values that are commented out # serve to show the default. +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + import datetime import os PROJECT_NAME = "psutil" -AUTHOR = "Giampaolo Rodola'" +AUTHOR = u"Giampaolo Rodola" THIS_YEAR = str(datetime.datetime.now().year) HERE = os.path.abspath(os.path.dirname(__file__)) @@ -39,7 +49,8 @@ def get_version(): VERSION = get_version() # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.0' +# +# 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 @@ -51,12 +62,16 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx'] # Add any paths that contain templates here, relative to this directory. -templates_path = ['_template'] +templates_path = ['_templates'] -# The suffix of source filenames. +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] source_suffix = '.rst' # The encoding of source files. +# # source_encoding = 'utf-8-sig' # The master toctree document. @@ -65,6 +80,7 @@ master_doc = 'index' # General information about the project. project = PROJECT_NAME copyright = '2009-%s, %s' % (THIS_YEAR, AUTHOR) +author = AUTHOR # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -72,35 +88,47 @@ copyright = '2009-%s, %s' % (THIS_YEAR, AUTHOR) # # The short X.Y version. version = VERSION +# The full version, including alpha/beta/rc tags. +release = VERSION # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -# language = None +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +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'] +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] # 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 +# +# 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 -autodoc_docstring_signature = 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. @@ -109,141 +137,240 @@ 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 + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False -# -- Options for HTML output ------------------------------------------------- + +# -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' # 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 = 'pydoctheme' -html_theme_options = {'collapsiblesidebar': True} +# +# html_theme_options = {} # Add any paths that contain custom themes here, relative to this directory. -html_theme_path = ["_themes"] +# html_theme_path = [] -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -html_title = "{project} {version} documentation".format(**locals()) +# The name for this set of Sphinx documents. +# "<project> v<release> documentation" by default. +# +# html_title = u'psutil v1.0' # 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 = 'logo.png' +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or +# 32x32 pixels large. -# 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 = '_static/favicon.ico' # 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'] -# 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' +# 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 None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. -html_use_smartypants = True +# +# html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -html_sidebars = { - 'index': 'indexsidebar.html', - '**': ['globaltoc.html', - 'relations.html', - 'sourcelink.html', - 'searchbox.html'] -} +# +# html_sidebars = {} # Additional templates that should be rendered to pages, maps page names to # template names. -# html_additional_pages = { -# 'index': 'indexcontent.html', -# } +# +# html_additional_pages = {} # If false, no module index is generated. -html_domain_indices = False +# +# html_domain_indices = True # If false, no index is generated. -html_use_index = True +# +# 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 <link> 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 +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + # Output file base name for HTML help builder. htmlhelp_basename = '%s-doc' % PROJECT_NAME -# -- Options for LaTeX output ------------------------------------------------ +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', -# The paper size ('letter' or 'a4'). -# latex_paper_size = 'letter' + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', -# The font size ('10pt', '11pt' or '12pt'). -# latex_font_size = '10pt' + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass -# [howto/manual]). +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). latex_documents = [ - ('index', '%s.tex' % PROJECT_NAME, - '%s documentation' % PROJECT_NAME, AUTHOR), + (master_doc, 'psutil.tex', u'psutil Documentation', + AUTHOR, 'manual'), ] -# The name of an image file (relative to this directory) to place at -# the top of the title page. +# 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 -# Additional stuff for the LaTeX preamble. -# latex_preamble = '' - # Documents to append as an appendix to all manuals. +# # latex_appendices = [] +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + # If false, no module index is generated. +# # latex_domain_indices = True -# -- Options for manual page output ------------------------------------------ +# -- Options for manual page output --------------------------------------- # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - ('index', PROJECT_NAME, '%s documentation' % PROJECT_NAME, [AUTHOR], 1) + (master_doc, 'psutil', u'psutil Documentation', + [author], 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 = [ + (master_doc, 'psutil', u'psutil Documentation', + author, 'psutil', '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 + + +html_context = { + 'css_files': [ + 'https://media.readthedocs.org/css/sphinx_rtd_theme.css', + 'https://media.readthedocs.org/css/readthedocs-doc-embed.css', + '_static/css/custom.css', + ], +} diff --git a/docs/index.rst b/docs/index.rst index 36123d96..b35c89bf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,13 +8,13 @@ psutil documentation Quick links ----------- -* `Home page <https://github.com/giampaolo/psutil>`__ -* `Install <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_ -* `Blog <http://grodola.blogspot.com/search/label/psutil>`__ -* `Forum <http://groups.google.com/group/psutil/topics>`__ -* `Download <https://pypi.python.org/pypi?:action=display&name=psutil#downloads>`__ -* `Development guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`_ -* `What's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`__ +- `Home page <https://github.com/giampaolo/psutil>`__ +- `Install <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_ +- `Blog <http://grodola.blogspot.com/search/label/psutil>`__ +- `Forum <http://groups.google.com/group/psutil/topics>`__ +- `Download <https://pypi.python.org/pypi?:action=display&name=psutil#downloads>`__ +- `Development guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`_ +- `What's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`__ About ----- @@ -25,11 +25,19 @@ retrieving information on running in **Python**. It is useful mainly for **system monitoring**, **profiling**, **limiting process resources** and the **management of running processes**. -It implements many functionalities offered by command line tools +It implements many functionalities offered by UNIX command line tools such as: *ps, top, lsof, netstat, ifconfig, who, df, kill, free, nice, ionice, iostat, iotop, uptime, pidof, tty, taskset, pmap*. -It currently supports **Linux, Windows, OSX, Sun Solaris, FreeBSD, OpenBSD** -and **NetBSD**, both **32-bit** and **64-bit** architectures, with Python +psutil currently supports the following platforms: + +- **Linux** +- **Windows** +- **OSX**, +- **FreeBSD, OpenBSD**, **NetBSD** +- **Sun Solaris** +- **AIX** + +...both **32-bit** and **64-bit** architectures, with Python versions from **2.6 to 3.6** (users of Python 2.4 and 2.5 may use `2.1.3 <https://pypi.python.org/pypi?name=psutil&version=2.1.3&:action=files>`__ version). `PyPy <http://pypy.org/>`__ is also known to work. @@ -155,12 +163,14 @@ CPU Return the number of logical CPUs in the system (same as `os.cpu_count() <http://docs.python.org/3/library/os.html#os.cpu_count>`__ - in Python 3.4). - This number is not equivalent to the number of CPUs the current process can - use. The number of usable CPUs can be obtained with + in Python 3.4) or ``None`` if undetermined. + This number may not be equivalent to the number of CPUs the current process + can actually use in case process CPU affinity has been changed or Linux + cgroups are being used. + The number of usable CPUs can be obtained with ``len(psutil.Process().cpu_affinity())``. If *logical* is ``False`` return the number of physical cores only (hyper - thread CPUs are excluded). Return ``None`` if undetermined. + thread CPUs are excluded). On OpenBSD and NetBSD ``psutil.cpu_count(logical=False)`` always return ``None``. Example on a system having 2 physical hyper-thread CPU cores: @@ -170,6 +180,11 @@ CPU >>> psutil.cpu_count(logical=False) 2 + Example returning the number of CPUs usable by the current process: + + >>> len(psutil.Process().cpu_affinity()) + 1 + .. function:: cpu_stats() Return various CPU statistics as a named tuple: @@ -404,6 +419,8 @@ Disks numbers will always be increasing or remain the same, but never decrease. ``disk_io_counters.cache_clear()`` can be used to invalidate the *nowrap* cache. + On Windows it may be ncessary to issue ``diskperf -y`` command from cmd.exe + first in order to enable IO counters. >>> import psutil >>> psutil.disk_io_counters() @@ -538,7 +555,7 @@ Network | ``"all"`` | the sum of all the possible families and protocols | +----------------+-----------------------------------------------------+ - On OSX this function requires root privileges. + On OSX and AIX this function requires root privileges. To get per-process connections use :meth:`Process.connections`. Also, see `netstat.py sample script <https://github.com/giampaolo/psutil/blob/master/scripts/netstat.py>`__. @@ -553,8 +570,8 @@ Network ...] .. note:: - (OSX) :class:`psutil.AccessDenied` is always raised unless running as root. - This is a limitation of the OS and ``lsof`` does the same. + (OSX and AIX) :class:`psutil.AccessDenied` is always raised unless running + as root. This is a limitation of the OS and ``lsof`` does the same. .. note:: (Solaris) UNIX sockets are not supported. @@ -687,7 +704,7 @@ Sensors .. warning:: - This API is experimental. Backward incompatible changes may occur if + this API is experimental. Backward incompatible changes may occur if deemed necessary. .. function:: sensors_fans() @@ -711,7 +728,7 @@ Sensors .. warning:: - This API is experimental. Backward incompatible changes may occur if + this API is experimental. Backward incompatible changes may occur if deemed necessary. .. function:: sensors_battery() @@ -751,9 +768,11 @@ Sensors .. versionadded:: 5.1.0 + .. versionchanged:: 5.4.2 added OSX support + .. warning:: - This API is experimental. Backward incompatible changes may occur if + this API is experimental. Backward incompatible changes may occur if deemed necessary. Other system info @@ -830,9 +849,9 @@ Functions Sorting order in which processes are returned is based on their PID. *attrs* and *ad_value* have the same meaning as in :meth:`Process.as_dict()`. - If *attrs* is specified :meth:`Process.as_dict()` is called and the resulting - dict is stored as a ``info`` attribute which is attached to the returned - :class:`Process` instance. + If *attrs* is specified :meth:`Process.as_dict()` is called interanally and + the resulting dict is stored as a ``info`` attribute which is attached to the + returned :class:`Process` instances. If *attrs* is an empty list it will retrieve all process info (slow). Example usage:: @@ -900,8 +919,8 @@ Functions ``callback`` is a function which gets called when one of the processes being waited on is terminated and a :class:`Process` instance is passed as callback argument). - This tunction will return as soon as all processes terminate or when - *timeout* occurs, if specified. + This function will return as soon as all processes terminate or when + *timeout* (seconds) occurs. Differently from :meth:`Process.wait` it will not raise :class:`TimeoutExpired` if timeout occurs. A typical use case may be: @@ -986,14 +1005,13 @@ Process class at the same time, make sure to use either :meth:`as_dict` or :meth:`oneshot` context manager. - .. warning:: + .. note:: - the way this class is bound to a process is via its **PID**. - That means that if the :class:`Process` instance is old enough and - the PID has been reused in the meantime you might end up interacting - with another process. + the way this class is bound to a process is uniquely via its **PID**. + That means that if the process terminates and the OS reuses its PID you may + end up interacting with another process. The only exceptions for which process identity is preemptively checked - (via PID + creation time) and guaranteed are for + (via PID + creation time) is for the following methods: :meth:`nice` (set), :meth:`ionice` (set), :meth:`cpu_affinity` (set), @@ -1003,12 +1021,13 @@ Process class :meth:`suspend` :meth:`resume`, :meth:`send_signal`, - :meth:`terminate`, and - :meth:`kill` - methods. + :meth:`terminate` + :meth:`kill`. To prevent this problem for all other methods you can use - :meth:`is_running()` before querying the process or use + :meth:`is_running()` before querying the process or :func:`process_iter()` in case you're iterating over all processes. + It must be noted though that unless you deal with very "old" (inactive) + :class:`Process` instances this will hardly represent a problem. .. method:: oneshot() @@ -1046,45 +1065,45 @@ Process class The last column (speedup) shows an approximation of the speedup you can get if you call all the methods together (best case scenario). - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | Linux | Windows | OSX | BSD | SunOS | - +==============================+===============================+==============================+==============================+==========================+ - | :meth:`cpu_num` | :meth:`~Process.cpu_percent` | :meth:`~Process.cpu_percent` | :meth:`cpu_num` | :meth:`name` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`~Process.cpu_percent` | :meth:`~Process.cpu_times` | :meth:`~Process.cpu_times` | :meth:`~Process.cpu_percent` | :meth:`cmdline` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`~Process.cpu_times` | :meth:`io_counters()` | :meth:`memory_info` | :meth:`~Process.cpu_times` | :meth:`create_time` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`create_time` | :meth:`ionice` | :meth:`memory_percent` | :meth:`create_time` | | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`name` | :meth:`memory_info` | :meth:`num_ctx_switches` | :meth:`gids` | :meth:`memory_info` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`ppid` | :meth:`nice` | :meth:`num_threads` | :meth:`io_counters` | :meth:`memory_percent` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`status` | :meth:`memory_maps` | | :meth:`name` | :meth:`nice` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`terminal` | :meth:`num_ctx_switches` | :meth:`create_time` | :meth:`memory_info` | :meth:`num_threads` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | | :meth:`num_handles` | :meth:`gids` | :meth:`memory_percent` | :meth:`ppid` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`gids` | :meth:`num_threads` | :meth:`name` | :meth:`num_ctx_switches` | :meth:`status` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`num_ctx_switches` | :meth:`username` | :meth:`ppid` | :meth:`ppid` | :meth:`terminal` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`num_threads` | | :meth:`status` | :meth:`status` | | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`uids` | | :meth:`terminal` | :meth:`terminal` | :meth:`gids` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`username` | | :meth:`uids` | :meth:`uids` | :meth:`uids` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | | | :meth:`username` | :meth:`username` | :meth:`username` | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`memory_full_info` | | | | | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | :meth:`memory_maps` | | | | | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ - | *speedup: +2.6x* | *speedup: +1.8x / +6.5x* | *speedup: +1.9x* | *speedup: +2.0x* | *speedup: +1.3x* | - +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+ + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | Linux | Windows | OSX | BSD | SunOS | AIX | + +==============================+===============================+==============================+==============================+==========================+==========================+ + | :meth:`cpu_num` | :meth:`cpu_percent` | :meth:`cpu_percent` | :meth:`cpu_num` | :meth:`name` | :meth:`name` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`cpu_percent` | :meth:`cpu_times` | :meth:`cpu_times` | :meth:`cpu_percent` | :meth:`cmdline` | :meth:`cmdline` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`cpu_times` | :meth:`io_counters()` | :meth:`memory_info` | :meth:`cpu_times` | :meth:`create_time` | :meth:`create_time` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`create_time` | :meth:`memory_info` | :meth:`memory_percent` | :meth:`create_time` | | | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`name` | :meth:`memory_maps` | :meth:`num_ctx_switches` | :meth:`gids` | :meth:`memory_info` | :meth:`memory_info` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`ppid` | :meth:`num_ctx_switches` | :meth:`num_threads` | :meth:`io_counters` | :meth:`memory_percent` | :meth:`memory_percent` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`status` | :meth:`num_handles` | | :meth:`name` | :meth:`num_threads` | :meth:`num_threads` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`terminal` | :meth:`num_threads` | :meth:`create_time` | :meth:`memory_info` | :meth:`ppid` | :meth:`ppid` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | | :meth:`username` | :meth:`gids` | :meth:`memory_percent` | :meth:`status` | :meth:`status` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`gids` | | :meth:`name` | :meth:`num_ctx_switches` | :meth:`terminal` | :meth:`terminal` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`num_ctx_switches` | | :meth:`ppid` | :meth:`ppid` | | | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`num_threads` | | :meth:`status` | :meth:`status` | :meth:`gids` | :meth:`gids` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`uids` | | :meth:`terminal` | :meth:`terminal` | :meth:`uids` | :meth:`uids` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`username` | | :meth:`uids` | :meth:`uids` | :meth:`username` | :meth:`username` | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | | | :meth:`username` | :meth:`username` | | | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`memory_full_info` | | | | | | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | :meth:`memory_maps` | | | | | | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ + | *speedup: +2.6x* | *speedup: +1.8x / +6.5x* | *speedup: +1.9x* | *speedup: +2.0x* | *speedup: +1.3x* | *speedup: +1.3x* | + +------------------------------+-------------------------------+------------------------------+------------------------------+--------------------------+--------------------------+ .. versionadded:: 5.0.0 @@ -1138,7 +1157,7 @@ Process class Availability: Linux, OSX, Windows, SunOS .. versionadded:: 4.0.0 - .. versionchanged:: 5.3.0: added SunOS support + .. versionchanged:: 5.3.0 added SunOS support .. method:: create_time() @@ -1351,7 +1370,7 @@ Process class >>> p.io_counters() pio(read_count=454556, write_count=3456, read_bytes=110592, write_bytes=0, read_chars=769931, write_chars=203) - Availability: all platforms except OSX and Solaris + Availability: Linux, BSD, Windows, AIX .. versionchanged:: 5.2.0 added *read_chars* and *write_chars* on Linux; added *other_count* and *other_bytes* on Windows. @@ -1361,6 +1380,8 @@ Process class The number voluntary and involuntary context switches performed by this process (cumulative). + .. versionchanged:: 5.4.1 added AIX support + .. method:: num_fds() The number of file descriptors currently opened by this process @@ -1496,33 +1517,33 @@ Process class The "portable" fields available on all plaforms are `rss` and `vms`. All numbers are expressed in bytes. - +---------+---------+-------+---------+------------------------------+ - | Linux | OSX | BSD | Solaris | Windows | - +=========+=========+=======+=========+==============================+ - | rss | rss | rss | rss | rss (alias for ``wset``) | - +---------+---------+-------+---------+------------------------------+ - | vms | vms | vms | vms | vms (alias for ``pagefile``) | - +---------+---------+-------+---------+------------------------------+ - | shared | pfaults | text | | num_page_faults | - +---------+---------+-------+---------+------------------------------+ - | text | pageins | data | | peak_wset | - +---------+---------+-------+---------+------------------------------+ - | lib | | stack | | wset | - +---------+---------+-------+---------+------------------------------+ - | data | | | | peak_paged_pool | - +---------+---------+-------+---------+------------------------------+ - | dirty | | | | paged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | peak_nonpaged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | nonpaged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | pagefile | - +---------+---------+-------+---------+------------------------------+ - | | | | | peak_pagefile | - +---------+---------+-------+---------+------------------------------+ - | | | | | private | - +---------+---------+-------+---------+------------------------------+ + +---------+---------+-------+---------+-----+------------------------------+ + | Linux | OSX | BSD | Solaris | AIX | Windows | + +=========+=========+=======+=========+=====+==============================+ + | rss | rss | rss | rss | rss | rss (alias for ``wset``) | + +---------+---------+-------+---------+-----+------------------------------+ + | vms | vms | vms | vms | vms | vms (alias for ``pagefile``) | + +---------+---------+-------+---------+-----+------------------------------+ + | shared | pfaults | text | | | num_page_faults | + +---------+---------+-------+---------+-----+------------------------------+ + | text | pageins | data | | | peak_wset | + +---------+---------+-------+---------+-----+------------------------------+ + | lib | | stack | | | wset | + +---------+---------+-------+---------+-----+------------------------------+ + | data | | | | | peak_paged_pool | + +---------+---------+-------+---------+-----+------------------------------+ + | dirty | | | | | paged_pool | + +---------+---------+-------+---------+-----+------------------------------+ + | | | | | | peak_nonpaged_pool | + +---------+---------+-------+---------+-----+------------------------------+ + | | | | | | nonpaged_pool | + +---------+---------+-------+---------+-----+------------------------------+ + | | | | | | pagefile | + +---------+---------+-------+---------+-----+------------------------------+ + | | | | | | peak_pagefile | + +---------+---------+-------+---------+-----+------------------------------+ + | | | | | | private | + +---------+---------+-------+---------+-----+------------------------------+ - **rss**: aka "Resident Set Size", this is the non-swapped physical memory a process has used. @@ -1693,13 +1714,13 @@ Process class pmmap_ext(addr='02829000-02ccf000', perms='rw-p', path='[heap]', rss=4743168, size=4874240, pss=4743168, shared_clean=0, shared_dirty=0, private_clean=0, private_dirty=4743168, referenced=4718592, anonymous=4743168, swap=0), ...] - Availability: All platforms except OpenBSD and NetBSD. + Availability: All platforms except OpenBSD, NetBSD and AIX. .. method:: children(recursive=False) - Return the children of this process as a list of :Class:`Process` objects, - preemptively checking whether PID has been reused. If recursive is `True` - return all the parent descendants. + Return the children of this process as a list of :class:`Process` + instances. + If recursive is `True` return all the parent descendants. Pseudo code example assuming *A == this process*: :: @@ -1719,7 +1740,7 @@ Process class Note that in the example above if process X disappears process Y won't be returned either as the reference to process A is lost. This concept is well summaried by this - `unit test <https://github.com/giampaolo/psutil/blob/fb9ae861cf3cf175c3da4a3cd4e558c6cbd6af91/psutil/tests/test_process.py#L1236-L1247>`__. + `unit test <https://github.com/giampaolo/psutil/blob/65a52341b55faaab41f68ebc4ed31f18f0929754/psutil/tests/test_process.py#L1064-L1075>`__. See also how to `kill a process tree <#kill-process-tree>`__ and `terminate my children <#terminate-my-children>`__. @@ -1855,6 +1876,10 @@ Process class (OpenBSD) "laddr" and "raddr" fields for UNIX sockets are always set to "". This is a limitation of the OS. + .. note:: + (AIX) :class:`psutil.AccessDenied` is always raised unless running + as root (lsof does the same). + .. versionchanged:: 5.3.0 : "laddr" and "raddr" are named tuples. .. method:: is64bit() @@ -1928,14 +1953,15 @@ Process class .. method:: wait(timeout=None) - Wait for process termination and if the process is a children of the - current one also return the exit code, else ``None``. On Windows there's + Wait for process termination and if the process is a child of the current + one also return the exit code, else ``None``. On Windows there's no such limitation (exit code is always returned). If the process is already terminated immediately return ``None`` instead of raising - :class:`NoSuchProcess`. If *timeout* is specified and process is still - alive raise :class:`TimeoutExpired` exception. It can also be used in a - non-blocking fashion by specifying ``timeout=0`` in which case it will - either return immediately or raise :class:`TimeoutExpired`. + :class:`NoSuchProcess`. + *timeout* is expressed in seconds. If specified and the process is still + alive raise :class:`TimeoutExpired` exception. + ``timeout=0`` can be used in non-blocking apps: it will either return + immediately or raise :class:`TimeoutExpired`. To wait for multiple processes use :func:`psutil.wait_procs()`. >>> import psutil @@ -2104,16 +2130,18 @@ Constants .. data:: OPENBSD .. data:: BSD .. data:: SUNOS +.. data:: AIX ``bool`` constants which define what platform you're on. E.g. if on Windows, :const:`WINDOWS` constant will be ``True``, all others will be ``False``. .. versionadded:: 4.0.0 + .. versionchanged:: 5.4.0 added AIX .. _const-procfs_path: .. data:: PROCFS_PATH - The path of the /proc filesystem on Linux and Solaris (defaults to + The path of the /proc filesystem on Linux, Solaris and AIX (defaults to ``"/proc"``). You may want to re-set this constant right after importing psutil in case your /proc filesystem is mounted elsewhere or if you want to retrieve @@ -2126,10 +2154,11 @@ Constants It must be noted that this trick works only for APIs which rely on /proc filesystem (e.g. `memory`_ APIs and most :class:`Process` class methods). - Availability: Linux, Solaris + Availability: Linux, Solaris, AIX .. versionadded:: 3.2.3 .. versionchanged:: 3.4.2 also available on Solaris. + .. versionchanged:: 5.4.0 also available on AIX. .. _const-pstatus: .. data:: STATUS_RUNNING @@ -2415,13 +2444,13 @@ resources. for p in procs: p.terminate() gone, alive = psutil.wait_procs(procs, timeout=timeout, callback=on_terminate) - if not alive: + if alive: # send SIGKILL for p in alive: print("process {} survived SIGTERM; trying SIGKILL" % p) p.kill() gone, alive = psutil.wait_procs(alive, timeout=timeout, callback=on_terminate) - if not alive: + if alive: # give up for p in alive: print("process {} survived SIGKILL; giving up" % p) @@ -2506,8 +2535,8 @@ Top 3 processes opening more file descriptors:: (2721, {'name': 'chrome', 'num_fds': 185}), (2650, {'name': 'chrome', 'num_fds': 354})] -Q&A -=== +FAQs +==== * Q: What Windows versions are supported? * A: From Windows **Vista** onwards, both 32 and 64 bit versions. @@ -2520,6 +2549,13 @@ Q&A ---- +* Q: What Python versions are supported? +* A: From 2.6 to 3.6, both 32 and 64 bit versions. Last version supporting + Python 2.4 and 2.5 is `psutil 2.1.3 <https://pypi.python.org/pypi?name=psutil&version=2.1.3&:action=files>`__. + PyPy is also known to work. + +---- + * Q: What SunOS versions are supported? * A: From Solaris 10 onwards. @@ -2542,7 +2578,7 @@ Q&A * Q: What about load average? * A: psutil does not expose any load average function as it's already available in python as - `os.getloadavg <https://docs.python.org/2/library/os.html#os.getloadavg>`__ + `os.getloadavg <https://docs.python.org/2/library/os.html#os.getloadavg>`__. Running tests ============= @@ -2566,6 +2602,30 @@ take a look at the Timeline ======== +- 2018-01-01: + `5.4.3 <https://pypi.python.org/pypi?name=psutil&version=5.4.3&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#542>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.4.2...release-5.4.3#files_bucket>`__ +- 2017-12-07: + `5.4.2 <https://pypi.python.org/pypi?name=psutil&version=5.4.2&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#542>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.4.1...release-5.4.2#files_bucket>`__ +- 2017-11-08: + `5.4.1 <https://pypi.python.org/pypi?name=psutil&version=5.4.1&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#541>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.4.0...release-5.4.1#files_bucket>`__ +- 2017-10-12: + `5.4.0 <https://pypi.python.org/pypi?name=psutil&version=5.4.0&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#540>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.3.1...release-5.4.0#files_bucket>`__ +- 2017-09-10: + `5.3.1 <https://pypi.python.org/pypi?name=psutil&version=5.3.1&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#530>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.3.0...release-5.3.1#files_bucket>`__ +- 2017-09-01: + `5.3.0 <https://pypi.python.org/pypi?name=psutil&version=5.3.0&:action=files>`__ - + `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#530>`__ - + `diff <https://github.com/giampaolo/psutil/compare/release-5.2.2...release-5.3.0#files_bucket>`__ - 2017-04-10: `5.2.2 <https://pypi.python.org/pypi?name=psutil&version=5.2.2&:action=files>`__ - `what's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst#522>`__ - |
