diff options
Diffstat (limited to 'python/psutil/docs')
| -rw-r--r-- | python/psutil/docs/Makefile | 177 | ||||
| -rw-r--r-- | python/psutil/docs/README | 15 | ||||
| -rw-r--r-- | python/psutil/docs/_static/copybutton.js | 57 | ||||
| -rw-r--r-- | python/psutil/docs/_static/favicon.ico | bin | 0 -> 15086 bytes | |||
| -rw-r--r-- | python/psutil/docs/_static/logo.png | bin | 0 -> 4922 bytes | |||
| -rw-r--r-- | python/psutil/docs/_static/sidebar.js | 161 | ||||
| -rw-r--r-- | python/psutil/docs/_template/globaltoc.html | 12 | ||||
| -rw-r--r-- | python/psutil/docs/_template/indexcontent.html | 4 | ||||
| -rw-r--r-- | python/psutil/docs/_template/indexsidebar.html | 8 | ||||
| -rw-r--r-- | python/psutil/docs/_template/page.html | 66 | ||||
| -rw-r--r-- | python/psutil/docs/_themes/pydoctheme/static/pydoctheme.css | 187 | ||||
| -rw-r--r-- | python/psutil/docs/_themes/pydoctheme/theme.conf | 23 | ||||
| -rw-r--r-- | python/psutil/docs/conf.py | 248 | ||||
| -rw-r--r-- | python/psutil/docs/index.rst | 1400 | ||||
| -rw-r--r-- | python/psutil/docs/make.bat | 242 | ||||
| -rw-r--r-- | python/psutil/docs/xxx | 11 |
16 files changed, 2611 insertions, 0 deletions
diff --git a/python/psutil/docs/Makefile b/python/psutil/docs/Makefile new file mode 100644 index 000000000..b23ab4ba8 --- /dev/null +++ b/python/psutil/docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +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 + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @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 " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @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" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @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)" + +clean: + rm -rf $(BUILDDIR) + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +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." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/psutil.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/psutil.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/psutil" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/psutil" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +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." + +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." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +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." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +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." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/python/psutil/docs/README b/python/psutil/docs/README new file mode 100644 index 000000000..3aaea8a5b --- /dev/null +++ b/python/psutil/docs/README @@ -0,0 +1,15 @@ +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/. +In case you want, you need to install sphinx first: + + $ pip install sphinx + +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 diff --git a/python/psutil/docs/_static/copybutton.js b/python/psutil/docs/_static/copybutton.js new file mode 100644 index 000000000..5d82c672b --- /dev/null +++ b/python/psutil/docs/_static/copybutton.js @@ -0,0 +1,57 @@ +$(document).ready(function() { + /* Add a [>>>] button on the top-right corner of code samples to hide + * the >>> and ... prompts and the output and thus make the code + * copyable. */ + var div = $('.highlight-python .highlight,' + + '.highlight-python3 .highlight') + var pre = div.find('pre'); + + // get the styles from the current theme + pre.parent().parent().css('position', 'relative'); + var hide_text = 'Hide the prompts and output'; + var show_text = 'Show the prompts and output'; + var border_width = pre.css('border-top-width'); + var border_style = pre.css('border-top-style'); + var border_color = pre.css('border-top-color'); + var button_styles = { + 'cursor':'pointer', 'position': 'absolute', 'top': '0', 'right': '0', + 'border-color': border_color, 'border-style': border_style, + 'border-width': border_width, 'color': border_color, 'text-size': '75%', + 'font-family': 'monospace', 'padding-left': '0.2em', 'padding-right': '0.2em', + 'border-radius': '0 3px 0 0' + } + + // create and add the button to all the code blocks that contain >>> + div.each(function(index) { + var jthis = $(this); + if (jthis.find('.gp').length > 0) { + var button = $('<span class="copybutton">>>></span>'); + button.css(button_styles) + button.attr('title', hide_text); + jthis.prepend(button); + } + // tracebacks (.gt) contain bare text elements that need to be + // wrapped in a span to work with .nextUntil() (see later) + jthis.find('pre:has(.gt)').contents().filter(function() { + return ((this.nodeType == 3) && (this.data.trim().length > 0)); + }).wrap('<span>'); + }); + + // define the behavior of the button when it's clicked + $('.copybutton').toggle( + function() { + var button = $(this); + button.parent().find('.go, .gp, .gt').hide(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'hidden'); + button.css('text-decoration', 'line-through'); + button.attr('title', show_text); + }, + function() { + var button = $(this); + button.parent().find('.go, .gp, .gt').show(); + button.next('pre').find('.gt').nextUntil('.gp, .go').css('visibility', 'visible'); + button.css('text-decoration', 'none'); + button.attr('title', hide_text); + }); +}); + diff --git a/python/psutil/docs/_static/favicon.ico b/python/psutil/docs/_static/favicon.ico Binary files differnew file mode 100644 index 000000000..c9efc5844 --- /dev/null +++ b/python/psutil/docs/_static/favicon.ico diff --git a/python/psutil/docs/_static/logo.png b/python/psutil/docs/_static/logo.png Binary files differnew file mode 100644 index 000000000..7d975ec9d --- /dev/null +++ b/python/psutil/docs/_static/logo.png diff --git a/python/psutil/docs/_static/sidebar.js b/python/psutil/docs/_static/sidebar.js new file mode 100644 index 000000000..337696391 --- /dev/null +++ b/python/psutil/docs/_static/sidebar.js @@ -0,0 +1,161 @@ +/* + * sidebar.js + * ~~~~~~~~~~ + * + * This script makes the Sphinx sidebar collapsible. + * + * .sphinxsidebar contains .sphinxsidebarwrapper. This script adds in + * .sphixsidebar, after .sphinxsidebarwrapper, the #sidebarbutton used to + * collapse and expand the sidebar. + * + * When the sidebar is collapsed the .sphinxsidebarwrapper is hidden and the + * width of the sidebar and the margin-left of the document are decreased. + * When the sidebar is expanded the opposite happens. This script saves a + * per-browser/per-session cookie used to remember the position of the sidebar + * among the pages. Once the browser is closed the cookie is deleted and the + * position reset to the default (expanded). + * + * :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +$(function() { + // global elements used by the functions. + // the 'sidebarbutton' element is defined as global after its + // creation, in the add_sidebar_button function + var bodywrapper = $('.bodywrapper'); + var sidebar = $('.sphinxsidebar'); + var sidebarwrapper = $('.sphinxsidebarwrapper'); + + // original margin-left of the bodywrapper and width of the sidebar + // with the sidebar expanded + var bw_margin_expanded = bodywrapper.css('margin-left'); + var ssb_width_expanded = sidebar.width(); + + // margin-left of the bodywrapper and width of the sidebar + // with the sidebar collapsed + var bw_margin_collapsed = '.8em'; + var ssb_width_collapsed = '.8em'; + + // colors used by the current theme + var dark_color = '#AAAAAA'; + var light_color = '#CCCCCC'; + + function sidebar_is_collapsed() { + return sidebarwrapper.is(':not(:visible)'); + } + + function toggle_sidebar() { + if (sidebar_is_collapsed()) + expand_sidebar(); + else + collapse_sidebar(); + } + + function collapse_sidebar() { + sidebarwrapper.hide(); + sidebar.css('width', ssb_width_collapsed); + bodywrapper.css('margin-left', bw_margin_collapsed); + sidebarbutton.css({ + 'margin-left': '0', + //'height': bodywrapper.height(), + 'height': sidebar.height(), + 'border-radius': '5px' + }); + sidebarbutton.find('span').text('»'); + sidebarbutton.attr('title', _('Expand sidebar')); + document.cookie = 'sidebar=collapsed'; + } + + function expand_sidebar() { + bodywrapper.css('margin-left', bw_margin_expanded); + sidebar.css('width', ssb_width_expanded); + sidebarwrapper.show(); + sidebarbutton.css({ + 'margin-left': ssb_width_expanded-12, + //'height': bodywrapper.height(), + 'height': sidebar.height(), + 'border-radius': '0 5px 5px 0' + }); + sidebarbutton.find('span').text('«'); + sidebarbutton.attr('title', _('Collapse sidebar')); + //sidebarwrapper.css({'padding-top': + // Math.max(window.pageYOffset - sidebarwrapper.offset().top, 10)}); + document.cookie = 'sidebar=expanded'; + } + + function add_sidebar_button() { + sidebarwrapper.css({ + 'float': 'left', + 'margin-right': '0', + 'width': ssb_width_expanded - 28 + }); + // create the button + sidebar.append( + '<div id="sidebarbutton"><span>«</span></div>' + ); + var sidebarbutton = $('#sidebarbutton'); + // find the height of the viewport to center the '<<' in the page + var viewport_height; + if (window.innerHeight) + viewport_height = window.innerHeight; + else + viewport_height = $(window).height(); + var sidebar_offset = sidebar.offset().top; + + var sidebar_height = sidebar.height(); + //var sidebar_height = Math.max(bodywrapper.height(), sidebar.height()); + sidebarbutton.find('span').css({ + 'display': 'block', + 'margin-top': sidebar_height/2 - 10 + //'margin-top': (viewport_height - sidebar.position().top - 20) / 2 + //'position': 'fixed', + //'top': Math.min(viewport_height/2, sidebar_height/2 + sidebar_offset) - 10 + }); + + sidebarbutton.click(toggle_sidebar); + sidebarbutton.attr('title', _('Collapse sidebar')); + sidebarbutton.css({ + 'border-radius': '0 5px 5px 0', + 'color': '#444444', + 'background-color': '#CCCCCC', + 'font-size': '1.2em', + 'cursor': 'pointer', + 'height': sidebar_height, + 'padding-top': '1px', + 'padding-left': '1px', + 'margin-left': ssb_width_expanded - 12 + }); + + sidebarbutton.hover( + function () { + $(this).css('background-color', dark_color); + }, + function () { + $(this).css('background-color', light_color); + } + ); + } + + function set_position_from_cookie() { + if (!document.cookie) + return; + var items = document.cookie.split(';'); + for(var k=0; k<items.length; k++) { + var key_val = items[k].split('='); + var key = key_val[0]; + if (key == 'sidebar') { + var value = key_val[1]; + if ((value == 'collapsed') && (!sidebar_is_collapsed())) + collapse_sidebar(); + else if ((value == 'expanded') && (sidebar_is_collapsed())) + expand_sidebar(); + } + } + } + + add_sidebar_button(); + var sidebarbutton = $('#sidebarbutton'); + set_position_from_cookie(); +}); diff --git a/python/psutil/docs/_template/globaltoc.html b/python/psutil/docs/_template/globaltoc.html new file mode 100644 index 000000000..f5fbb406c --- /dev/null +++ b/python/psutil/docs/_template/globaltoc.html @@ -0,0 +1,12 @@ +{# + 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/python/psutil/docs/_template/indexcontent.html b/python/psutil/docs/_template/indexcontent.html new file mode 100644 index 000000000..dd5e7249a --- /dev/null +++ b/python/psutil/docs/_template/indexcontent.html @@ -0,0 +1,4 @@ +{% extends "defindex.html" %} +{% block tables %} + +{% endblock %} diff --git a/python/psutil/docs/_template/indexsidebar.html b/python/psutil/docs/_template/indexsidebar.html new file mode 100644 index 000000000..903675d10 --- /dev/null +++ b/python/psutil/docs/_template/indexsidebar.html @@ -0,0 +1,8 @@ +<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/python/psutil/docs/_template/page.html b/python/psutil/docs/_template/page.html new file mode 100644 index 000000000..04b47b415 --- /dev/null +++ b/python/psutil/docs/_template/page.html @@ -0,0 +1,66 @@ +{% 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/python/psutil/docs/_themes/pydoctheme/static/pydoctheme.css b/python/psutil/docs/_themes/pydoctheme/static/pydoctheme.css new file mode 100644 index 000000000..4196e5582 --- /dev/null +++ b/python/psutil/docs/_themes/pydoctheme/static/pydoctheme.css @@ -0,0 +1,187 @@ +@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; +} diff --git a/python/psutil/docs/_themes/pydoctheme/theme.conf b/python/psutil/docs/_themes/pydoctheme/theme.conf new file mode 100644 index 000000000..95b97e536 --- /dev/null +++ b/python/psutil/docs/_themes/pydoctheme/theme.conf @@ -0,0 +1,23 @@ +[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/python/psutil/docs/conf.py b/python/psutil/docs/conf.py new file mode 100644 index 000000000..9fa163b65 --- /dev/null +++ b/python/psutil/docs/conf.py @@ -0,0 +1,248 @@ +# -*- coding: utf-8 -*- +# +# psutil documentation build configuration file, created by +# sphinx-quickstart. +# +# 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 datetime +import os + + +PROJECT_NAME = "psutil" +AUTHOR = "Giampaolo Rodola'" +THIS_YEAR = str(datetime.datetime.now().year) +HERE = os.path.abspath(os.path.dirname(__file__)) + + +def get_version(): + INIT = os.path.abspath(os.path.join(HERE, '../psutil/__init__.py')) + with open(INIT, 'r') as f: + for line in f: + if line.startswith('__version__'): + ret = eval(line.strip().split(' = ')[1]) + assert ret.count('.') == 2, ret + for num in ret.split('.'): + assert num.isdigit(), ret + return ret + else: + raise ValueError("couldn't find version string") + +VERSION = get_version() + +# 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.coverage', + 'sphinx.ext.pngmath', + 'sphinx.ext.viewcode', + 'sphinx.ext.intersphinx'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_template'] + +# 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 = PROJECT_NAME +copyright = '2009-%s, %s' % (THIS_YEAR, 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 +# built documents. +# +# The short X.Y version. +version = VERSION + +# 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 + +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. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +# 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} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = ["_themes"] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +html_title = "{project} {version} documentation".format(**locals()) + +# 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' + +# 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' + +# 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 = { + 'index': 'indexsidebar.html', + '**': ['globaltoc.html', + 'relations.html', + 'sourcelink.html', + 'searchbox.html'] +} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# html_additional_pages = { +# 'index': 'indexcontent.html', +# } + +# If false, no module index is generated. +html_domain_indices = False + +# 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 <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 + +# Output file base name for HTML help builder. +htmlhelp_basename = '%s-doc' % PROJECT_NAME + +# -- Options for LaTeX output ------------------------------------------------ + +# The paper size ('letter' or 'a4'). +# latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +# latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', '%s.tex' % PROJECT_NAME, + '%s documentation' % PROJECT_NAME, AUTHOR), +] + +# 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 = [] + +# 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', PROJECT_NAME, '%s documentation' % PROJECT_NAME, [AUTHOR], 1) +] + +# If true, show URL addresses after external links. +# man_show_urls = False diff --git a/python/psutil/docs/index.rst b/python/psutil/docs/index.rst new file mode 100644 index 000000000..443019226 --- /dev/null +++ b/python/psutil/docs/index.rst @@ -0,0 +1,1400 @@ +.. module:: psutil + :synopsis: psutil module +.. moduleauthor:: Giampaolo Rodola' <grodola@gmail.com> + +.. warning:: + + This documentation refers to new 2.X version of psutil. + Instructions on how to port existing 1.2.1 code are + `here <http://grodola.blogspot.com/2014/01/psutil-20-porting.html>`__. + Old 1.2.1 documentation is still available + `here <https://code.google.com/p/psutil/wiki/Documentation>`__. + +psutil documentation +==================== + +Quick links +----------- + +* `Home page <https://github.com/giampaolo/psutil>`__ +* `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>`__ +* `Installation <https://github.com/giampaolo/psutil/blob/master/INSTALL.rst>`_ +* `Development guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`_ +* `What's new <https://github.com/giampaolo/psutil/blob/master/HISTORY.rst>`__ + +About +----- + +From project's home page: + + psutil (python system and process utilities) is a cross-platform library for + retrieving information on running + **processes** and **system utilization** (CPU, memory, disks, network) in + **Python**. + It is useful mainly for **system monitoring**, **profiling** and **limiting + process resources** and **management of running processes**. + It implements many functionalities offered by 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, FreeBSD** and **Sun Solaris**, + both **32-bit** and **64-bit** architectures, with Python versions from + **2.6 to 3.4** (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. + +The psutil documentation you're reading is distributed as a single HTML page. + +System related functions +======================== + +CPU +--- + +.. function:: cpu_times(percpu=False) + + Return system CPU times as a namedtuple. + Every attribute represents the seconds the CPU has spent in the given mode. + The attributes availability varies depending on the platform: + + - **user** + - **system** + - **idle** + - **nice** *(UNIX)* + - **iowait** *(Linux)* + - **irq** *(Linux, FreeBSD)* + - **softirq** *(Linux)* + - **steal** *(Linux 2.6.11+)* + - **guest** *(Linux 2.6.24+)* + - **guest_nice** *(Linux 3.2.0+)* + + When *percpu* is ``True`` return a list of namedtuples for each logical CPU + on the system. + First element of the list refers to first CPU, second element to second CPU + and so on. + The order of the list is consistent across calls. + Example output on Linux: + + >>> import psutil + >>> psutil.cpu_times() + scputimes(user=17411.7, nice=77.99, system=3797.02, idle=51266.57, iowait=732.58, irq=0.01, softirq=142.43, steal=0.0, guest=0.0, guest_nice=0.0) + +.. function:: cpu_percent(interval=None, percpu=False) + + Return a float representing the current system-wide CPU utilization as a + percentage. When *interval* is > ``0.0`` compares system CPU times elapsed + before and after the interval (blocking). + When *interval* is ``0.0`` or ``None`` compares system CPU times elapsed + since last call or module import, returning immediately. + That means the first time this is called it will return a meaningless ``0.0`` + value which you are supposed to ignore. + In this case is recommended for accuracy that this function be called with at + least ``0.1`` seconds between calls. + When *percpu* is ``True`` returns a list of floats representing the + utilization as a percentage for each CPU. + First element of the list refers to first CPU, second element to second CPU + and so on. The order of the list is consistent across calls. + + >>> import psutil + >>> # blocking + >>> psutil.cpu_percent(interval=1) + 2.0 + >>> # non-blocking (percentage since last call) + >>> psutil.cpu_percent(interval=None) + 2.9 + >>> # blocking, per-cpu + >>> psutil.cpu_percent(interval=1, percpu=True) + [2.0, 1.0] + >>> + + .. warning:: + + the first time this function is called with *interval* = ``0.0`` or ``None`` + it will return a meaningless ``0.0`` value which you are supposed to + ignore. + +.. function:: cpu_times_percent(interval=None, percpu=False) + + Same as :func:`cpu_percent()` but provides utilization percentages for each + specific CPU time as is returned by + :func:`psutil.cpu_times(percpu=True)<cpu_times()>`. + *interval* and + *percpu* arguments have the same meaning as in :func:`cpu_percent()`. + + .. warning:: + + the first time this function is called with *interval* = ``0.0`` or + ``None`` it will return a meaningless ``0.0`` value which you are supposed + to ignore. + +.. function:: cpu_count(logical=True) + + 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). + If *logical* is ``False`` return the number of physical cores only (hyper + thread CPUs are excluded). Return ``None`` if undetermined. + + >>> import psutil + >>> psutil.cpu_count() + 4 + >>> psutil.cpu_count(logical=False) + 2 + >>> + +Memory +------ + +.. function:: virtual_memory() + + Return statistics about system memory usage as a namedtuple including the + following fields, expressed in bytes: + + - **total**: total physical memory available. + - **available**: the actual amount of available memory that can be given + instantly to processes that request more memory in bytes; this is + calculated by summing different memory values depending on the platform + (e.g. free + buffers + cached on Linux) and it is supposed to be used to + monitor actual memory usage in a cross platform fashion. + - **percent**: the percentage usage calculated as + ``(total - available) / total * 100``. + - **used**: memory used, calculated differently depending on the platform and + designed for informational purposes only. + - **free**: memory not being used at all (zeroed) that is readily available; + note that this doesn't reflect the actual memory available (use 'available' + instead). + + Platform-specific fields: + + - **active**: (UNIX): memory currently in use or very recently used, and so + it is in RAM. + - **inactive**: (UNIX): memory that is marked as not used. + - **buffers**: (Linux, BSD): cache for things like file system metadata. + - **cached**: (Linux, BSD): cache for various things. + - **wired**: (BSD, OSX): memory that is marked to always stay in RAM. It is + never moved to disk. + - **shared**: (BSD): memory that may be simultaneously accessed by multiple + processes. + + The sum of **used** and **available** does not necessarily equal **total**. + On Windows **available** and **free** are the same. + See `examples/meminfo.py <https://github.com/giampaolo/psutil/blob/master/examples/meminfo.py>`__ + script providing an example on how to convert bytes in a human readable form. + + >>> import psutil + >>> mem = psutil.virtual_memory() + >>> mem + svmem(total=8374149120L, available=1247768576L, percent=85.1, used=8246628352L, free=127520768L, active=3208777728, inactive=1133408256, buffers=342413312L, cached=777834496) + >>> + >>> THRESHOLD = 100 * 1024 * 1024 # 100MB + >>> if mem.available <= THRESHOLD: + ... print("warning") + ... + >>> + + +.. function:: swap_memory() + + Return system swap memory statistics as a namedtuple including the following + fields: + + * **total**: total swap memory in bytes + * **used**: used swap memory in bytes + * **free**: free swap memory in bytes + * **percent**: the percentage usage calculated as ``(total - available) / total * 100`` + * **sin**: the number of bytes the system has swapped in from disk + (cumulative) + * **sout**: the number of bytes the system has swapped out from disk + (cumulative) + + **sin** and **sout** on Windows are meaningless and are always set to ``0``. + See `examples/meminfo.py <https://github.com/giampaolo/psutil/blob/master/examples/meminfo.py>`__ + script providing an example on how to convert bytes in a human readable form. + + >>> import psutil + >>> psutil.swap_memory() + sswap(total=2097147904L, used=886620160L, free=1210527744L, percent=42.3, sin=1050411008, sout=1906720768) + +Disks +----- + +.. function:: disk_partitions(all=False) + + Return all mounted disk partitions as a list of namedtuples including device, + mount point and filesystem type, similarly to "df" command on UNIX. If *all* + parameter is ``False`` return physical devices only (e.g. hard disks, cd-rom + drives, USB keys) and ignore all others (e.g. memory partitions such as + `/dev/shm <http://www.cyberciti.biz/tips/what-is-devshm-and-its-practical-usage.html>`__). + Namedtuple's **fstype** field is a string which varies depending on the + platform. + On Linux it can be one of the values found in /proc/filesystems (e.g. + ``'ext3'`` for an ext3 hard drive o ``'iso9660'`` for the CD-ROM drive). + On Windows it is determined via + `GetDriveType <http://msdn.microsoft.com/en-us/library/aa364939(v=vs.85).aspx>`__ + and can be either ``"removable"``, ``"fixed"``, ``"remote"``, ``"cdrom"``, + ``"unmounted"`` or ``"ramdisk"``. On OSX and FreeBSD it is retrieved via + `getfsstat(2) <http://www.manpagez.com/man/2/getfsstat/>`__. See + `disk_usage.py <https://github.com/giampaolo/psutil/blob/master/examples/disk_usage.py>`__ + script providing an example usage. + + >>> import psutil + >>> psutil.disk_partitions() + [sdiskpart(device='/dev/sda3', mountpoint='/', fstype='ext4', opts='rw,errors=remount-ro'), + sdiskpart(device='/dev/sda7', mountpoint='/home', fstype='ext4', opts='rw')] + +.. function:: disk_usage(path) + + Return disk usage statistics about the given *path* as a namedtuple including + **total**, **used** and **free** space expressed in bytes, plus the + **percentage** usage. + `OSError <http://docs.python.org/3/library/exceptions.html#OSError>`__ is + raised if *path* does not exist. See + `examples/disk_usage.py <https://github.com/giampaolo/psutil/blob/master/examples/disk_usage.py>`__ + script providing an example usage. Starting from + `Python 3.3 <http://bugs.python.org/issue12442>`__ this is also + available as + `shutil.disk_usage() <http://docs.python.org/3/library/shutil.html#shutil.disk_usage>`__. + See + `disk_usage.py <https://github.com/giampaolo/psutil/blob/master/examples/disk_usage.py>`__ + script providing an example usage. + + >>> import psutil + >>> psutil.disk_usage('/') + sdiskusage(total=21378641920, used=4809781248, free=15482871808, percent=22.5) + +.. function:: disk_io_counters(perdisk=False) + + Return system-wide disk I/O statistics as a namedtuple including the + following fields: + + - **read_count**: number of reads + - **write_count**: number of writes + - **read_bytes**: number of bytes read + - **write_bytes**: number of bytes written + - **read_time**: time spent reading from disk (in milliseconds) + - **write_time**: time spent writing to disk (in milliseconds) + + If *perdisk* is ``True`` return the same information for every physical disk + installed on the system as a dictionary with partition names as the keys and + the namedtuple described above as the values. + See `examples/iotop.py <https://github.com/giampaolo/psutil/blob/master/examples/iotop.py>`__ + for an example application. + + >>> import psutil + >>> psutil.disk_io_counters() + sdiskio(read_count=8141, write_count=2431, read_bytes=290203, write_bytes=537676, read_time=5868, write_time=94922) + >>> + >>> psutil.disk_io_counters(perdisk=True) + {'sda1': sdiskio(read_count=920, write_count=1, read_bytes=2933248, write_bytes=512, read_time=6016, write_time=4), + 'sda2': sdiskio(read_count=18707, write_count=8830, read_bytes=6060, write_bytes=3443, read_time=24585, write_time=1572), + 'sdb1': sdiskio(read_count=161, write_count=0, read_bytes=786432, write_bytes=0, read_time=44, write_time=0)} + +Network +------- + +.. function:: net_io_counters(pernic=False) + + Return system-wide network I/O statistics as a namedtuple including the + following attributes: + + - **bytes_sent**: number of bytes sent + - **bytes_recv**: number of bytes received + - **packets_sent**: number of packets sent + - **packets_recv**: number of packets received + - **errin**: total number of errors while receiving + - **errout**: total number of errors while sending + - **dropin**: total number of incoming packets which were dropped + - **dropout**: total number of outgoing packets which were dropped (always 0 + on OSX and BSD) + + If *pernic* is ``True`` return the same information for every network + interface installed on the system as a dictionary with network interface + names as the keys and the namedtuple described above as the values. + See `examples/nettop.py <https://github.com/giampaolo/psutil/blob/master/examples/nettop.py>`__ + for an example application. + + >>> import psutil + >>> psutil.net_io_counters() + snetio(bytes_sent=14508483, bytes_recv=62749361, packets_sent=84311, packets_recv=94888, errin=0, errout=0, dropin=0, dropout=0) + >>> + >>> psutil.net_io_counters(pernic=True) + {'lo': snetio(bytes_sent=547971, bytes_recv=547971, packets_sent=5075, packets_recv=5075, errin=0, errout=0, dropin=0, dropout=0), + 'wlan0': snetio(bytes_sent=13921765, bytes_recv=62162574, packets_sent=79097, packets_recv=89648, errin=0, errout=0, dropin=0, dropout=0)} + +.. function:: net_connections(kind='inet') + + Return system-wide socket connections as a list of namedtuples. + Every namedtuple provides 7 attributes: + + - **fd**: the socket file descriptor, if retrievable, else ``-1``. + If the connection refers to the current process this may be passed to + `socket.fromfd() <http://docs.python.org/library/socket.html#socket.fromfd>`__ + to obtain a usable socket object. + - **family**: the address family, either `AF_INET + <http://docs.python.org//library/socket.html#socket.AF_INET>`__, + `AF_INET6 <http://docs.python.org//library/socket.html#socket.AF_INET6>`__ + or `AF_UNIX <http://docs.python.org//library/socket.html#socket.AF_UNIX>`__. + - **type**: the address type, either `SOCK_STREAM + <http://docs.python.org//library/socket.html#socket.SOCK_STREAM>`__ or + `SOCK_DGRAM + <http://docs.python.org//library/socket.html#socket.SOCK_DGRAM>`__. + - **laddr**: the local address as a ``(ip, port)`` tuple or a ``path`` + in case of AF_UNIX sockets. + - **raddr**: the remote address as a ``(ip, port)`` tuple or an absolute + ``path`` in case of UNIX sockets. + When the remote endpoint is not connected you'll get an empty tuple + (AF_INET*) or ``None`` (AF_UNIX). + On Linux AF_UNIX sockets will always have this set to ``None``. + - **status**: represents the status of a TCP connection. The return value + is one of the :data:`psutil.CONN_* <psutil.CONN_ESTABLISHED>` constants + (a string). + For UDP and UNIX sockets this is always going to be + :const:`psutil.CONN_NONE`. + - **pid**: the PID of the process which opened the socket, if retrievable, + else ``None``. On some platforms (e.g. Linux) the availability of this + field changes depending on process privileges (root is needed). + + The *kind* parameter is a string which filters for connections that fit the + following criteria: + + .. table:: + + +----------------+-----------------------------------------------------+ + | **Kind value** | **Connections using** | + +================+=====================================================+ + | "inet" | IPv4 and IPv6 | + +----------------+-----------------------------------------------------+ + | "inet4" | IPv4 | + +----------------+-----------------------------------------------------+ + | "inet6" | IPv6 | + +----------------+-----------------------------------------------------+ + | "tcp" | TCP | + +----------------+-----------------------------------------------------+ + | "tcp4" | TCP over IPv4 | + +----------------+-----------------------------------------------------+ + | "tcp6" | TCP over IPv6 | + +----------------+-----------------------------------------------------+ + | "udp" | UDP | + +----------------+-----------------------------------------------------+ + | "udp4" | UDP over IPv4 | + +----------------+-----------------------------------------------------+ + | "udp6" | UDP over IPv6 | + +----------------+-----------------------------------------------------+ + | "unix" | UNIX socket (both UDP and TCP protocols) | + +----------------+-----------------------------------------------------+ + | "all" | the sum of all the possible families and protocols | + +----------------+-----------------------------------------------------+ + + On OSX 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/examples/netstat.py>`__. + Example: + + >>> import psutil + >>> psutil.net_connections() + [pconn(fd=115, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 48776), raddr=('93.186.135.91', 80), status='ESTABLISHED', pid=1254), + pconn(fd=117, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 43761), raddr=('72.14.234.100', 80), status='CLOSING', pid=2987), + pconn(fd=-1, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 60759), raddr=('72.14.234.104', 80), status='ESTABLISHED', pid=None), + pconn(fd=-1, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 51314), raddr=('72.14.234.83', 443), status='SYN_SENT', pid=None) + ...] + + .. note:: (OSX) :class:`psutil.AccessDenied` is always raised unless running + as root (lsof does the same). + .. note:: (Solaris) UNIX sockets are not supported. + + .. versionadded:: 2.1.0 + +.. function:: net_if_addrs() + + Return the addresses associated to each NIC (network interface card) + installed on the system as a dictionary whose keys are the NIC names and + value is a list of namedtuples for each address assigned to the NIC. + Each namedtuple includes 4 fields: + + - **family** + - **address** + - **netmask** + - **broadcast** + + *family* can be either + `AF_INET <http://docs.python.org//library/socket.html#socket.AF_INET>`__, + `AF_INET6 <http://docs.python.org//library/socket.html#socket.AF_INET6>`__ + or :const:`psutil.AF_LINK`, which refers to a MAC address. + *address* is the primary address, *netmask* and *broadcast* may be ``None``. + Example:: + + >>> import psutil + >>> psutil.net_if_addrs() + {'lo': [snic(family=<AddressFamily.AF_INET: 2>, address='127.0.0.1', netmask='255.0.0.0', broadcast='127.0.0.1'), + snic(family=<AddressFamily.AF_INET6: 10>, address='::1', netmask='ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff', broadcast=None), + snic(family=<AddressFamily.AF_LINK: 17>, address='00:00:00:00:00:00', netmask=None, broadcast='00:00:00:00:00:00')], + 'wlan0': [snic(family=<AddressFamily.AF_INET: 2>, address='192.168.1.3', netmask='255.255.255.0', broadcast='192.168.1.255'), + snic(family=<AddressFamily.AF_INET6: 10>, address='fe80::c685:8ff:fe45:641%wlan0', netmask='ffff:ffff:ffff:ffff::', broadcast=None), + snic(family=<AddressFamily.AF_LINK: 17>, address='c4:85:08:45:06:41', netmask=None, broadcast='ff:ff:ff:ff:ff:ff')]} + >>> + + See also `examples/ifconfig.py <https://github.com/giampaolo/psutil/blob/master/examples/ifconfig.py>`__ + for an example application. + + .. note:: if you're interested in others families (e.g. AF_BLUETOOTH) you can + use the more powerful `netifaces <https://pypi.python.org/pypi/netifaces/>`__ + extension. + + .. note:: you can have more than one address of the same family associated + with each interface (that's why dict values are lists). + + *New in 3.0.0* + +.. function:: net_if_stats() + + Return information about each NIC (network interface card) installed on the + system as a dictionary whose keys are the NIC names and value is a namedtuple + with the following fields: + + - **isup** + - **duplex** + - **speed** + - **mtu** + + *isup* is a boolean indicating whether the NIC is up and running, *duplex* + can be either :const:`NIC_DUPLEX_FULL`, :const:`NIC_DUPLEX_HALF` or + :const:`NIC_DUPLEX_UNKNOWN`, *speed* is the NIC speed expressed in mega bits + (MB), if it can't be determined (e.g. 'localhost') it will be set to ``0``, + *mtu* is the maximum transmission unit expressed in bytes. + See also `examples/ifconfig.py <https://github.com/giampaolo/psutil/blob/master/examples/ifconfig.py>`__ + for an example application. + Example: + + >>> import psutil + >>> psutil.net_if_stats() + {'eth0': snicstats(isup=True, duplex=<NicDuplex.NIC_DUPLEX_FULL: 2>, speed=100, mtu=1500), + 'lo': snicstats(isup=True, duplex=<NicDuplex.NIC_DUPLEX_UNKNOWN: 0>, speed=0, mtu=65536)} + + *New in 3.0.0* + + +Other system info +----------------- + +.. function:: users() + + Return users currently connected on the system as a list of namedtuples + including the following fields: + + - **user**: the name of the user. + - **terminal**: the tty or pseudo-tty associated with the user, if any, + else ``None``. + - **host**: the host name associated with the entry, if any. + - **started**: the creation time as a floating point number expressed in + seconds since the epoch. + + Example:: + + >>> import psutil + >>> psutil.users() + [suser(name='giampaolo', terminal='pts/2', host='localhost', started=1340737536.0), + suser(name='giampaolo', terminal='pts/3', host='localhost', started=1340737792.0)] + +.. function:: boot_time() + + Return the system boot time expressed in seconds since the epoch. + Example: + + .. code-block:: python + + >>> import psutil, datetime + >>> psutil.boot_time() + 1389563460.0 + >>> datetime.datetime.fromtimestamp(psutil.boot_time()).strftime("%Y-%m-%d %H:%M:%S") + '2014-01-12 22:51:00' + +Processes +========= + +Functions +--------- + +.. function:: pids() + + Return a list of current running PIDs. To iterate over all processes + :func:`process_iter()` should be preferred. + +.. function:: pid_exists(pid) + + Check whether the given PID exists in the current process list. This is + faster than doing ``"pid in psutil.pids()"`` and should be preferred. + +.. function:: process_iter() + + Return an iterator yielding a :class:`Process` class instance for all running + processes on the local machine. + Every instance is only created once and then cached into an internal table + which is updated every time an element is yielded. + Cached :class:`Process` instances are checked for identity so that you're + safe in case a PID has been reused by another process, in which case the + cached instance is updated. + This is should be preferred over :func:`psutil.pids()` for iterating over + processes. + Sorting order in which processes are returned is + based on their PID. Example usage:: + + import psutil + + for proc in psutil.process_iter(): + try: + pinfo = proc.as_dict(attrs=['pid', 'name']) + except psutil.NoSuchProcess: + pass + else: + print(pinfo) + +.. function:: wait_procs(procs, timeout=None, callback=None) + + Convenience function which waits for a list of :class:`Process` instances to + terminate. Return a ``(gone, alive)`` tuple indicating which processes are + gone and which ones are still alive. The *gone* ones will have a new + *returncode* attribute indicating process exit status (it may be ``None``). + ``callback`` is a function which gets called every time a process terminates + (a :class:`Process` instance is passed as callback argument). Function will + return as soon as all processes terminate or when timeout occurs. Tipical use + case is: + + - send SIGTERM to a list of processes + - give them some time to terminate + - send SIGKILL to those ones which are still alive + + Example:: + + import psutil + + def on_terminate(proc): + print("process {} terminated with exit code {}".format(proc, proc.returncode)) + + procs = [...] # a list of Process instances + for p in procs: + p.terminate() + gone, alive = wait_procs(procs, timeout=3, callback=on_terminate) + for p in alive: + p.kill() + +Exceptions +---------- + +.. class:: Error() + + Base exception class. All other exceptions inherit from this one. + +.. class:: NoSuchProcess(pid, name=None, msg=None) + + Raised by :class:`Process` class methods when no process with the given + *pid* is found in the current process list or when a process no longer + exists. "name" is the name the process had before disappearing + and gets set only if :meth:`Process.name()` was previosly called. + +.. class:: ZombieProcess(pid, name=None, ppid=None, msg=None) + + This may be raised by :class:`Process` class methods when querying a zombie + process on UNIX (Windows doesn't have zombie processes). Depending on the + method called the OS may be able to succeed in retrieving the process + information or not. + Note: this is a subclass of :class:`NoSuchProcess` so if you're not + interested in retrieving zombies (e.g. when using :func:`process_iter()`) + you can ignore this exception and just catch :class:`NoSuchProcess`. + + *New in 3.0.0* + +.. class:: AccessDenied(pid=None, name=None, msg=None) + + Raised by :class:`Process` class methods when permission to perform an + action is denied. "name" is the name of the process (may be ``None``). + +.. class:: TimeoutExpired(seconds, pid=None, name=None, msg=None) + + Raised by :meth:`Process.wait` if timeout expires and process is still + alive. + +Process class +------------- + +.. class:: Process(pid=None) + + Represents an OS process with the given *pid*. If *pid* is omitted current + process *pid* (`os.getpid() <http://docs.python.org/library/os.html#os.getpid>`__) + is used. + Raise :class:`NoSuchProcess` if *pid* does not exist. + When accessing methods of this class always be prepared to catch + :class:`NoSuchProcess` and :class:`AccessDenied` exceptions. + `hash() <http://docs.python.org/2/library/functions.html#hash>`__ builtin can + be used against instances of this class in order to identify a process + univocally over time (the hash is determined by mixing process PID + and creation time). As such it can also be used with + `set()s <http://docs.python.org/2/library/stdtypes.html#types-set>`__. + + .. warning:: + + the way this class is bound to a process is uniquely via its **PID**. + That means that if the :class:`Process` instance is old enough and + the PID has been reused by another process in the meantime you might end up + interacting with another process. + The only exceptions for which process identity is pre-emptively checked + (via PID + creation time) and guaranteed are for + :meth:`nice` (set), + :meth:`ionice` (set), + :meth:`cpu_affinity` (set), + :meth:`rlimit` (set), + :meth:`children`, + :meth:`parent`, + :meth:`suspend` + :meth:`resume`, + :meth:`send_signal`, + :meth:`terminate`, and + :meth:`kill` + methods. + To prevent this problem for all other methods you can use + :meth:`is_running()` before querying the process or use + :func:`process_iter()` in case you're iterating over all processes. + + .. attribute:: pid + + The process PID. + + .. method:: ppid() + + The process parent pid. On Windows the return value is cached after first + call. + + .. method:: name() + + The process name. The return value is cached after first call. + + .. method:: exe() + + The process executable as an absolute path. + On some systems this may also be an empty string. + The return value is cached after first call. + + .. method:: cmdline() + + The command line this process has been called with. + + .. method:: create_time() + + The process creation time as a floating point number expressed in seconds + since the epoch, in + `UTC <http://en.wikipedia.org/wiki/Coordinated_universal_time>`__. + The return value is cached after first call. + + >>> import psutil, datetime + >>> p = psutil.Process() + >>> p.create_time() + 1307289803.47 + >>> datetime.datetime.fromtimestamp(p.create_time()).strftime("%Y-%m-%d %H:%M:%S") + '2011-03-05 18:03:52' + + .. method:: as_dict(attrs=None, ad_value=None) + + Utility method returning process information as a hashable dictionary. + If *attrs* is specified it must be a list of strings reflecting available + :class:`Process` class's attribute names (e.g. ``['cpu_times', 'name']``) + else all public (read only) attributes are assumed. *ad_value* is the + value which gets assigned to a dict key in case :class:`AccessDenied` + or :class:`ZombieProcess` exception is raised when retrieving that + particular process information. + + >>> import psutil + >>> p = psutil.Process() + >>> p.as_dict(attrs=['pid', 'name', 'username']) + {'username': 'giampaolo', 'pid': 12366, 'name': 'python'} + + .. versionchanged:: 3.0.0 *ad_value* is used also when incurring into + :class:`ZombieProcess` exception, not only :class:`AccessDenied` + + .. method:: parent() + + Utility method which returns the parent process as a :class:`Process` + object pre-emptively checking whether PID has been reused. If no parent + PID is known return ``None``. + + .. method:: status() + + The current process status as a string. The returned string is one of the + :data:`psutil.STATUS_*<psutil.STATUS_RUNNING>` constants. + + .. method:: cwd() + + The process current working directory as an absolute path. + + .. method:: username() + + The name of the user that owns the process. On UNIX this is calculated by + using real process uid. + + .. method:: uids() + + The **real**, **effective** and **saved** user ids of this process as a + namedtuple. This is the same as + `os.getresuid() <http://docs.python.org//library/os.html#os.getresuid>`__ + but can be used for every process PID. + + Availability: UNIX + + .. method:: gids() + + The **real**, **effective** and **saved** group ids of this process as a + namedtuple. This is the same as + `os.getresgid() <http://docs.python.org//library/os.html#os.getresgid>`__ + but can be used for every process PID. + + Availability: UNIX + + .. method:: terminal() + + The terminal associated with this process, if any, else ``None``. This is + similar to "tty" command but can be used for every process PID. + + Availability: UNIX + + .. method:: nice(value=None) + + Get or set process + `niceness <blogs.techrepublic.com.com/opensource/?p=140>`__ (priority). + On UNIX this is a number which usually goes from ``-20`` to ``20``. + The higher the nice value, the lower the priority of the process. + + >>> import psutil + >>> p = psutil.Process() + >>> p.nice(10) # set + >>> p.nice() # get + 10 + >>> + + Starting from `Python 3.3 <http://bugs.python.org/issue10784>`__ this + functionality is also available as + `os.getpriority() <http://docs.python.org/3/library/os.html#os.getpriority>`__ + and + `os.setpriority() <http://docs.python.org/3/library/os.html#os.setpriority>`__ + (UNIX only). + + On Windows this is available as well by using + `GetPriorityClass <http://msdn.microsoft.com/en-us/library/ms683211(v=vs.85).aspx>`__ + and `SetPriorityClass <http://msdn.microsoft.com/en-us/library/ms686219(v=vs.85).aspx>`__ + and *value* is one of the + :data:`psutil.*_PRIORITY_CLASS <psutil.ABOVE_NORMAL_PRIORITY_CLASS>` + constants. + Example which increases process priority on Windows: + + >>> p.nice(psutil.HIGH_PRIORITY_CLASS) + + .. method:: ionice(ioclass=None, value=None) + + Get or set + `process I/O niceness <http://friedcpu.wordpress.com/2007/07/17/why-arent-you-using-ionice-yet/>`__ (priority). + On Linux *ioclass* is one of the + :data:`psutil.IOPRIO_CLASS_*<psutil.IOPRIO_CLASS_NONE>` constants. + *value* is a number which goes from ``0`` to ``7``. The higher the value, + the lower the I/O priority of the process. On Windows only *ioclass* is + used and it can be set to ``2`` (normal), ``1`` (low) or ``0`` (very low). + The example below sets IDLE priority class for the current process, + meaning it will only get I/O time when no other process needs the disk: + + >>> import psutil + >>> p = psutil.Process() + >>> p.ionice(psutil.IOPRIO_CLASS_IDLE) # set + >>> p.ionice() # get + pionice(ioclass=<IOPriority.IOPRIO_CLASS_IDLE: 3>, value=0) + >>> + + On Windows only *ioclass* is used and it can be set to ``2`` (normal), + ``1`` (low) or ``0`` (very low). + + Availability: Linux and Windows > Vista + + .. versionchanged:: 3.0.0 on >= Python 3.4 the returned ``ioclass`` + constant is an `enum <https://docs.python.org/3/library/enum.html#module-enum>`__ + instead of a plain integer. + + .. method:: rlimit(resource, limits=None) + + Get or set process resource limits (see + `man prlimit <http://linux.die.net/man/2/prlimit>`__). *resource* is one of + the :data:`psutil.RLIMIT_* <psutil.RLIMIT_INFINITY>` constants. + *limits* is a ``(soft, hard)`` tuple. + This is the same as `resource.getrlimit() <http://docs.python.org/library/resource.html#resource.getrlimit>`__ + and `resource.setrlimit() <http://docs.python.org/library/resource.html#resource.setrlimit>`__ + but can be used for every process PID and only on Linux. + Example: + + >>> import psutil + >>> p = psutil.Process() + >>> # process may open no more than 128 file descriptors + >>> p.rlimit(psutil.RLIMIT_NOFILE, (128, 128)) + >>> # process may create files no bigger than 1024 bytes + >>> p.rlimit(psutil.RLIMIT_FSIZE, (1024, 1024)) + >>> # get + >>> p.rlimit(psutil.RLIMIT_FSIZE) + (1024, 1024) + >>> + + Availability: Linux + + .. method:: io_counters() + + Return process I/O statistics as a namedtuple including the number of read + and write operations performed by the process and the amount of bytes read + and written. For Linux refer to + `/proc filesysem documentation <https://www.kernel.org/doc/Documentation/filesystems/proc.txt>`__. + On BSD there's apparently no way to retrieve bytes counters, hence ``-1`` + is returned for **read_bytes** and **write_bytes** fields. OSX is not + supported. + + >>> import psutil + >>> p = psutil.Process() + >>> p.io_counters() + pio(read_count=454556, write_count=3456, read_bytes=110592, write_bytes=0) + + Availability: all platforms except OSX and Solaris + + .. method:: num_ctx_switches() + + The number voluntary and involuntary context switches performed by + this process. + + .. method:: num_fds() + + The number of file descriptors used by this process. + + Availability: UNIX + + .. method:: num_handles() + + The number of handles used by this process. + + Availability: Windows + + .. method:: num_threads() + + The number of threads currently used by this process. + + .. method:: threads() + + Return threads opened by process as a list of namedtuples including thread + id and thread CPU times (user/system). + + .. method:: cpu_times() + + Return a tuple whose values are process CPU **user** and **system** + times which means the amount of time expressed in seconds that a process + has spent in + `user / system mode <http://stackoverflow.com/questions/556405/what-do-real-user-and-sys-mean-in-the-output-of-time1>`__. + This is similar to + `os.times() <http://docs.python.org//library/os.html#os.times>`__ + but can be used for every process PID. + + .. method:: cpu_percent(interval=None) + + Return a float representing the process CPU utilization as a percentage. + When *interval* is > ``0.0`` compares process times to system CPU times + elapsed before and after the interval (blocking). When interval is ``0.0`` + or ``None`` compares process times to system CPU times elapsed since last + call, returning immediately. That means the first time this is called it + will return a meaningless ``0.0`` value which you are supposed to ignore. + In this case is recommended for accuracy that this function be called a + second time with at least ``0.1`` seconds between calls. Example: + + >>> import psutil + >>> p = psutil.Process() + >>> + >>> # blocking + >>> p.cpu_percent(interval=1) + 2.0 + >>> # non-blocking (percentage since last call) + >>> p.cpu_percent(interval=None) + 2.9 + >>> + + .. note:: + a percentage > 100 is legitimate as it can result from a process with + multiple threads running on different CPU cores. + + .. warning:: + the first time this method is called with interval = ``0.0`` or + ``None`` it will return a meaningless ``0.0`` value which you are + supposed to ignore. + + .. method:: cpu_affinity(cpus=None) + + Get or set process current + `CPU affinity <http://www.linuxjournal.com/article/6799?page=0,0>`__. + CPU affinity consists in telling the OS to run a certain process on a + limited set of CPUs only. The number of eligible CPUs can be obtained with + ``list(range(psutil.cpu_count()))``. On set raises ``ValueError`` in case + an invalid CPU number is specified. + + >>> import psutil + >>> psutil.cpu_count() + 4 + >>> p = psutil.Process() + >>> p.cpu_affinity() # get + [0, 1, 2, 3] + >>> p.cpu_affinity([0]) # set; from now on, process will run on CPU #0 only + >>> p.cpu_affinity() + [0] + >>> + >>> # reset affinity against all CPUs + >>> all_cpus = list(range(psutil.cpu_count())) + >>> p.cpu_affinity(all_cpus) + >>> + + Availability: Linux, Windows, BSD + + .. versionchanged:: 2.2.0 added support for FreeBSD + + .. method:: memory_info() + + Return a tuple representing RSS (Resident Set Size) and VMS (Virtual + Memory Size) in bytes. On UNIX *rss* and *vms* are the same values shown + by ps. On Windows *rss* and *vms* refer to "Mem Usage" and "VM Size" + columns of taskmgr.exe. For more detailed memory stats use + :meth:`memory_info_ex`. + + .. method:: memory_info_ex() + + Return a namedtuple with variable fields depending on the platform + representing extended memory information about the process. + All numbers are expressed in bytes. + + +--------+---------+-------+-------+--------------------+ + | Linux | OSX | BSD | SunOS | Windows | + +========+=========+=======+=======+====================+ + | rss | rss | rss | rss | num_page_faults | + +--------+---------+-------+-------+--------------------+ + | vms | vms | vms | vms | peak_wset | + +--------+---------+-------+-------+--------------------+ + | shared | pfaults | text | | wset | + +--------+---------+-------+-------+--------------------+ + | text | pageins | data | | peak_paged_pool | + +--------+---------+-------+-------+--------------------+ + | lib | | stack | | paged_pool | + +--------+---------+-------+-------+--------------------+ + | data | | | | peak_nonpaged_pool | + +--------+---------+-------+-------+--------------------+ + | dirty | | | | nonpaged_pool | + +--------+---------+-------+-------+--------------------+ + | | | | | pagefile | + +--------+---------+-------+-------+--------------------+ + | | | | | peak_pagefile | + +--------+---------+-------+-------+--------------------+ + | | | | | private | + +--------+---------+-------+-------+--------------------+ + + Windows metrics are extracted from + `PROCESS_MEMORY_COUNTERS_EX <http://msdn.microsoft.com/en-us/library/windows/desktop/ms684874(v=vs.85).aspx>`__ structure. + Example on Linux: + + >>> import psutil + >>> p = psutil.Process() + >>> p.memory_info_ex() + pextmem(rss=15491072, vms=84025344, shared=5206016, text=2555904, lib=0, data=9891840, dirty=0) + + .. method:: memory_percent() + + Compare physical system memory to process resident memory (RSS) and + calculate process memory utilization as a percentage. + + .. method:: memory_maps(grouped=True) + + Return process's mapped memory regions as a list of namedtuples whose + fields are variable depending on the platform. As such, portable + applications should rely on namedtuple's `path` and `rss` fields only. + This method is useful to obtain a detailed representation of process + memory usage as explained + `here <http://bmaurer.blogspot.it/2006/03/memory-usage-with-smaps.html>`__. + If *grouped* is ``True`` the mapped regions with the same *path* are + grouped together and the different memory fields are summed. If *grouped* + is ``False`` every mapped region is shown as a single entity and the + namedtuple will also include the mapped region's address space (*addr*) + and permission set (*perms*). + See `examples/pmap.py <https://github.com/giampaolo/psutil/blob/master/examples/pmap.py>`__ + for an example application. + + >>> import psutil + >>> p = psutil.Process() + >>> p.memory_maps() + [pmmap_grouped(path='/lib/x8664-linux-gnu/libutil-2.15.so', rss=16384, anonymous=8192, swap=0), + pmmap_grouped(path='/lib/x8664-linux-gnu/libc-2.15.so', rss=6384, anonymous=15, swap=0), + pmmap_grouped(path='/lib/x8664-linux-gnu/libcrypto.so.0.1', rss=34124, anonymous=1245, swap=0), + pmmap_grouped(path='[heap]', rss=54653, anonymous=8192, swap=0), + pmmap_grouped(path='[stack]', rss=1542, anonymous=166, swap=0), + ...] + >>> + + .. method:: children(recursive=False) + + Return the children of this process as a list of :Class:`Process` objects, + pre-emptively checking whether PID has been reused. If recursive is `True` + return all the parent descendants. + Example assuming *A == this process*: + :: + + A ─┐ + │ + ├─ B (child) ─┐ + │ └─ X (grandchild) ─┐ + │ └─ Y (great grandchild) + ├─ C (child) + └─ D (child) + + >>> p.children() + B, C, D + >>> p.children(recursive=True) + B, X, Y, C, D + + 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. + + .. method:: open_files() + + Return regular files opened by process as a list of namedtuples including + the absolute file name and the file descriptor number (on Windows this is + always ``-1``). Example: + + >>> import psutil + >>> f = open('file.ext', 'w') + >>> p = psutil.Process() + >>> p.open_files() + [popenfile(path='/home/giampaolo/svn/psutil/file.ext', fd=3)] + + .. warning:: + on Windows this is not fully reliable as due to some limitations of the + Windows API the underlying implementation may hang when retrieving + certain file handles. + In order to work around that psutil on Windows Vista (and higher) spawns + a thread and kills it if it's not responding after 100ms. + That implies that on Windows this method is not guaranteed to enumerate + all regular file handles (see full discusion + `here <https://github.com/giampaolo/psutil/pull/597>`_). + + .. warning:: + on FreeBSD this method can return files with a 'null' path (see + `issue 595 <https://github.com/giampaolo/psutil/pull/595>`_). + + .. versionchanged:: 3.1.0 no longer hangs on Windows. + + .. method:: connections(kind="inet") + + Return socket connections opened by process as a list of namedtuples. + To get system-wide connections use :func:`psutil.net_connections()`. + Every namedtuple provides 6 attributes: + + - **fd**: the socket file descriptor. This can be passed to + `socket.fromfd() <http://docs.python.org/library/socket.html#socket.fromfd>`__ + to obtain a usable socket object. + This is only available on UNIX; on Windows ``-1`` is always returned. + - **family**: the address family, either `AF_INET + <http://docs.python.org//library/socket.html#socket.AF_INET>`__, + `AF_INET6 <http://docs.python.org//library/socket.html#socket.AF_INET6>`__ + or `AF_UNIX <http://docs.python.org//library/socket.html#socket.AF_UNIX>`__. + - **type**: the address type, either `SOCK_STREAM + <http://docs.python.org//library/socket.html#socket.SOCK_STREAM>`__ or + `SOCK_DGRAM + <http://docs.python.org//library/socket.html#socket.SOCK_DGRAM>`__. + - **laddr**: the local address as a ``(ip, port)`` tuple or a ``path`` + in case of AF_UNIX sockets. + - **raddr**: the remote address as a ``(ip, port)`` tuple or an absolute + ``path`` in case of UNIX sockets. + When the remote endpoint is not connected you'll get an empty tuple + (AF_INET) or ``None`` (AF_UNIX). + On Linux AF_UNIX sockets will always have this set to ``None``. + - **status**: represents the status of a TCP connection. The return value + is one of the :data:`psutil.CONN_* <psutil.CONN_ESTABLISHED>` constants. + For UDP and UNIX sockets this is always going to be + :const:`psutil.CONN_NONE`. + + The *kind* parameter is a string which filters for connections that fit the + following criteria: + + .. table:: + + +----------------+-----------------------------------------------------+ + | **Kind value** | **Connections using** | + +================+=====================================================+ + | "inet" | IPv4 and IPv6 | + +----------------+-----------------------------------------------------+ + | "inet4" | IPv4 | + +----------------+-----------------------------------------------------+ + | "inet6" | IPv6 | + +----------------+-----------------------------------------------------+ + | "tcp" | TCP | + +----------------+-----------------------------------------------------+ + | "tcp4" | TCP over IPv4 | + +----------------+-----------------------------------------------------+ + | "tcp6" | TCP over IPv6 | + +----------------+-----------------------------------------------------+ + | "udp" | UDP | + +----------------+-----------------------------------------------------+ + | "udp4" | UDP over IPv4 | + +----------------+-----------------------------------------------------+ + | "udp6" | UDP over IPv6 | + +----------------+-----------------------------------------------------+ + | "unix" | UNIX socket (both UDP and TCP protocols) | + +----------------+-----------------------------------------------------+ + | "all" | the sum of all the possible families and protocols | + +----------------+-----------------------------------------------------+ + + Example: + + >>> import psutil + >>> p = psutil.Process(1694) + >>> p.name() + 'firefox' + >>> p.connections() + [pconn(fd=115, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 48776), raddr=('93.186.135.91', 80), status='ESTABLISHED'), + pconn(fd=117, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 43761), raddr=('72.14.234.100', 80), status='CLOSING'), + pconn(fd=119, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 60759), raddr=('72.14.234.104', 80), status='ESTABLISHED'), + pconn(fd=123, family=<AddressFamily.AF_INET: 2>, type=<SocketType.SOCK_STREAM: 1>, laddr=('10.0.0.1', 51314), raddr=('72.14.234.83', 443), status='SYN_SENT')] + + .. method:: is_running() + + Return whether the current process is running in the current process list. + This is reliable also in case the process is gone and its PID reused by + another process, therefore it must be preferred over doing + ``psutil.pid_exists(p.pid)``. + + .. note:: + this will return ``True`` also if the process is a zombie + (``p.status() == psutil.STATUS_ZOMBIE``). + + .. method:: send_signal(signal) + + Send a signal to process (see + `signal module <http://docs.python.org//library/signal.html>`__ + constants) pre-emptively checking whether PID has been reused. + This is the same as ``os.kill(pid, sig)``. + On Windows only **SIGTERM** is valid and is treated as an alias for + :meth:`kill()`. + + .. method:: suspend() + + Suspend process execution with **SIGSTOP** signal pre-emptively checking + whether PID has been reused. + On UNIX this is the same as ``os.kill(pid, signal.SIGSTOP)``. + On Windows this is done by suspending all process threads execution. + + .. method:: resume() + + Resume process execution with **SIGCONT** signal pre-emptively checking + whether PID has been reused. + On UNIX this is the same as ``os.kill(pid, signal.SIGCONT)``. + On Windows this is done by resuming all process threads execution. + + .. method:: terminate() + + Terminate the process with **SIGTERM** signal pre-emptively checking + whether PID has been reused. + On UNIX this is the same as ``os.kill(pid, signal.SIGTERM)``. + On Windows this is an alias for :meth:`kill`. + + .. method:: kill() + + Kill the current process by using **SIGKILL** signal pre-emptively + checking whether PID has been reused. + On UNIX this is the same as ``os.kill(pid, signal.SIGKILL)``. + On Windows this is done by using + `TerminateProcess <http://msdn.microsoft.com/en-us/library/windows/desktop/ms686714(v=vs.85).aspx>`__. + + .. 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 + 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`. + To wait for multiple processes use :func:`psutil.wait_procs()`. + + +Popen class +----------- + +.. class:: Popen(*args, **kwargs) + + A more convenient interface to stdlib + `subprocess.Popen <http://docs.python.org/library/subprocess.html#subprocess.Popen>`__. + It starts a sub process and deals with it exactly as when using + `subprocess.Popen <http://docs.python.org/library/subprocess.html#subprocess.Popen>`__ + but in addition it also provides all the methods of + :class:`psutil.Process` class in a single interface. + For method names common to both classes such as + :meth:`send_signal() <psutil.Process.send_signal()>`, + :meth:`terminate() <psutil.Process.terminate()>` and + :meth:`kill() <psutil.Process.kill()>` + :class:`psutil.Process` implementation takes precedence. + For a complete documentation refer to + `subprocess module documentation <http://docs.python.org/library/subprocess.html>`__. + + .. note:: + + Unlike `subprocess.Popen <http://docs.python.org/library/subprocess.html#subprocess.Popen>`__ + this class pre-emptively checks wheter PID has been reused on + :meth:`send_signal() <psutil.Process.send_signal()>`, + :meth:`terminate() <psutil.Process.terminate()>` and + :meth:`kill() <psutil.Process.kill()>` + so that you can't accidentally terminate another process, fixing + http://bugs.python.org/issue6973. + + >>> import psutil + >>> from subprocess import PIPE + >>> + >>> p = psutil.Popen(["/usr/bin/python", "-c", "print('hello')"], stdout=PIPE) + >>> p.name() + 'python' + >>> p.username() + 'giampaolo' + >>> p.communicate() + ('hello\n', None) + >>> p.wait(timeout=2) + 0 + >>> + +Constants +========= + +.. _const-pstatus: +.. data:: STATUS_RUNNING + STATUS_SLEEPING + STATUS_DISK_SLEEP + STATUS_STOPPED + STATUS_TRACING_STOP + STATUS_ZOMBIE + STATUS_DEAD + STATUS_WAKE_KILL + STATUS_WAKING + STATUS_IDLE + STATUS_LOCKED + STATUS_WAITING + + A set of strings representing the status of a process. + Returned by :meth:`psutil.Process.status()`. + +.. _const-conn: +.. data:: CONN_ESTABLISHED + CONN_SYN_SENT + CONN_SYN_RECV + CONN_FIN_WAIT1 + CONN_FIN_WAIT2 + CONN_TIME_WAIT + CONN_CLOSE + CONN_CLOSE_WAIT + CONN_LAST_ACK + CONN_LISTEN + CONN_CLOSING + CONN_NONE + CONN_DELETE_TCB (Windows) + CONN_IDLE (Solaris) + CONN_BOUND (Solaris) + + A set of strings representing the status of a TCP connection. + Returned by :meth:`psutil.Process.connections()` (`status` field). + +.. _const-prio: +.. data:: ABOVE_NORMAL_PRIORITY_CLASS + BELOW_NORMAL_PRIORITY_CLASS + HIGH_PRIORITY_CLASS + IDLE_PRIORITY_CLASS + NORMAL_PRIORITY_CLASS + REALTIME_PRIORITY_CLASS + + A set of integers representing the priority of a process on Windows (see + `MSDN documentation <http://msdn.microsoft.com/en-us/library/ms686219(v=vs.85).aspx>`__). + They can be used in conjunction with + :meth:`psutil.Process.nice()` to get or set process priority. + + Availability: Windows + + .. versionchanged:: 3.0.0 on Python >= 3.4 these constants are + `enums <https://docs.python.org/3/library/enum.html#module-enum>`__ + instead of a plain integer. + +.. _const-ioprio: +.. data:: IOPRIO_CLASS_NONE + IOPRIO_CLASS_RT + IOPRIO_CLASS_BE + IOPRIO_CLASS_IDLE + + A set of integers representing the I/O priority of a process on Linux. They + can be used in conjunction with :meth:`psutil.Process.ionice()` to get or set + process I/O priority. + *IOPRIO_CLASS_NONE* and *IOPRIO_CLASS_BE* (best effort) is the default for + any process that hasn't set a specific I/O priority. + *IOPRIO_CLASS_RT* (real time) means the process is given first access to the + disk, regardless of what else is going on in the system. + *IOPRIO_CLASS_IDLE* means the process will get I/O time when no-one else + needs the disk. + For further information refer to manuals of + `ionice <http://linux.die.net/man/1/ionice>`__ + command line utility or + `ioprio_get <http://linux.die.net/man/2/ioprio_get>`__ + system call. + + Availability: Linux + + .. versionchanged:: 3.0.0 on Python >= 3.4 thse constants are + `enums <https://docs.python.org/3/library/enum.html#module-enum>`__ + instead of a plain integer. + +.. _const-rlimit: +.. data:: RLIMIT_INFINITY + RLIMIT_AS + RLIMIT_CORE + RLIMIT_CPU + RLIMIT_DATA + RLIMIT_FSIZE + RLIMIT_LOCKS + RLIMIT_MEMLOCK + RLIMIT_MSGQUEUE + RLIMIT_NICE + RLIMIT_NOFILE + RLIMIT_NPROC + RLIMIT_RSS + RLIMIT_RTPRIO + RLIMIT_RTTIME + RLIMIT_RTPRIO + RLIMIT_SIGPENDING + RLIMIT_STACK + + Constants used for getting and setting process resource limits to be used in + conjunction with :meth:`psutil.Process.rlimit()`. See + `man prlimit <http://linux.die.net/man/2/prlimit>`__ for futher information. + + Availability: Linux + +.. _const-aflink: +.. data:: AF_LINK + + Constant which identifies a MAC address associated with a network interface. + To be used in conjunction with :func:`psutil.net_if_addrs()`. + + *New in 3.0.0* + +.. _const-duplex: +.. data:: NIC_DUPLEX_FULL + NIC_DUPLEX_HALF + NIC_DUPLEX_UNKNOWN + + Constants which identifies whether a NIC (network interface card) has full or + half mode speed. NIC_DUPLEX_FULL means the NIC is able to send and receive + data (files) simultaneously, NIC_DUPLEX_FULL means the NIC can either send or + receive data at a time. + To be used in conjunction with :func:`psutil.net_if_stats()`. + + *New in 3.0.0* + +Development guide +================= + +If you plan on hacking on psutil (e.g. want to add a new feature or fix a bug) +take a look at the +`development guide <https://github.com/giampaolo/psutil/blob/master/DEVGUIDE.rst>`_. diff --git a/python/psutil/docs/make.bat b/python/psutil/docs/make.bat new file mode 100644 index 000000000..9bc67515c --- /dev/null +++ b/python/psutil/docs/make.bat @@ -0,0 +1,242 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + 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. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + 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 + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\psutil.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\psutil.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %BUILDDIR%/.. + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +:end diff --git a/python/psutil/docs/xxx b/python/psutil/docs/xxx new file mode 100644 index 000000000..b78d53f2d --- /dev/null +++ b/python/psutil/docs/xxx @@ -0,0 +1,11 @@ +cpu 1974613 1749 485728 6305758 80280 15 5924 0 0 0 + +cpu0 519156 374 132999 5977865 72925 10 1458 0 0 0 + +cpu1 524667 401 125931 108960 2110 4 2214 0 0 0 + +cpu2 462286 520 117046 109514 2666 0 828 0 0 0 + +cpu3 468502 453 109750 109418 2578 0 1424 0 0 0 + + |
