From 029fbdfbc976a3f0432a0110c1c2e58e3ac33a09 Mon Sep 17 00:00:00 2001 From: Giampaolo Rodola Date: Mon, 6 Jun 2016 01:16:43 +0200 Subject: [PATCH] fix doc indentation --- docs/index.rst | 925 +++++++++++++++++++++++++------------------------ 1 file changed, 474 insertions(+), 451 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index f9032a6c4..11786a4f7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -730,154 +730,155 @@ Process class .. attribute:: pid - The process PID. + The process PID. .. method:: ppid() - The process parent pid. On Windows the return value is cached after first - call. + The process parent pid. On Windows the return value is cached after first + call. .. method:: name() - The process name. + The process name. .. 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. + 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. + The command line this process has been called with. .. method:: environ() - The environment variables of the process as a dict. Note: this might not - reflect changes made after the process started. + The environment variables of the process as a dict. Note: this might not + reflect changes made after the process started. - Availability: Linux, OSX, Windows + Availability: Linux, OSX, Windows - .. versionadded:: 4.0.0 + .. versionadded:: 4.0.0 .. method:: create_time() - The process creation time as a floating point number expressed in seconds - since the epoch, in - `UTC `__. - The return value is cached after first call. + The process creation time as a floating point number expressed in seconds + since the epoch, in + `UTC `__. + 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' + >>> 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 retrieving multiple process information as a 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. + Utility method retrieving multiple process information as a 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'} + >>> 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` + .. 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 preemptively checking whether PID has been reused. If no parent - PID is known return ``None``. + Utility method which returns the parent process as a :class:`Process` + object preemptively 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_*` constants. + The current process status as a string. The returned string is one of the + :data:`psutil.STATUS_*` constants. .. method:: cwd() - The process current working directory as an absolute path. + 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. + 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() `__ - but can be used for any process PID. + The real, effective and saved user ids of this process as a + namedtuple. This is the same as + `os.getresuid() `__ + but can be used for any process PID. - Availability: UNIX + Availability: UNIX .. method:: gids() - The real, effective and saved group ids of this process as a - namedtuple. This is the same as - `os.getresgid() `__ - but can be used for any process PID. + The real, effective and saved group ids of this process as a + namedtuple. This is the same as + `os.getresgid() `__ + but can be used for any process PID. - Availability: UNIX + 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 any process PID. + The terminal associated with this process, if any, else ``None``. This is + similar to "tty" command but can be used for any process PID. - Availability: UNIX + Availability: UNIX .. method:: nice(value=None) - Get or set process - `niceness `__ (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 `__ this - functionality is also available as - `os.getpriority() `__ - and - `os.setpriority() `__ - (UNIX only). - On Windows this is implemented via - `GetPriorityClass `__ - and `SetPriorityClass `__ - Windows APIs and *value* is one of the - :data:`psutil.*_PRIORITY_CLASS ` - constants reflecting the MSDN documentation. - Example which increases process priority on Windows: - - >>> p.nice(psutil.HIGH_PRIORITY_CLASS) + Get or set process + `niceness `__ (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 `__ this + functionality is also available as + `os.getpriority() `__ + and + `os.setpriority() `__ + (UNIX only). + On Windows this is implemented via + `GetPriorityClass `__ + and `SetPriorityClass `__ + Windows APIs and *value* is one of the + :data:`psutil.*_PRIORITY_CLASS ` + constants reflecting the MSDN documentation. + 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 `__ (priority). - On Linux *ioclass* is one of the - :data:`psutil.IOPRIO_CLASS_*` 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: + Get or set + `process I/O niceness `__ (priority). + On Linux *ioclass* is one of the + :data:`psutil.IOPRIO_CLASS_*` 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() @@ -886,27 +887,27 @@ Process class pionice(ioclass=, value=0) >>> - On Windows only *ioclass* is used and it can be set to ``2`` (normal), - ``1`` (low) or ``0`` (very low). + 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 + Availability: Linux and Windows > Vista - .. versionchanged:: - 3.0.0 on Python >= 3.4 the returned ``ioclass`` constant is an - `enum `__ - instead of a plain integer. + .. versionchanged:: + 3.0.0 on Python >= 3.4 the returned ``ioclass`` constant is an + `enum `__ + instead of a plain integer. .. method:: rlimit(resource, limits=None) - Get or set process resource limits (see - `man prlimit `__). *resource* is one - of the :data:`psutil.RLIMIT_* ` constants. - *limits* is a ``(soft, hard)`` tuple. - This is the same as `resource.getrlimit() `__ - and `resource.setrlimit() `__ - but can be used for any process PID, not only - `os.getpid() `__. - Example: + Get or set process resource limits (see + `man prlimit `__). *resource* is one + of the :data:`psutil.RLIMIT_* ` constants. + *limits* is a ``(soft, hard)`` tuple. + This is the same as `resource.getrlimit() `__ + and `resource.setrlimit() `__ + but can be used for any process PID, not only + `os.getpid() `__. + Example: >>> import psutil >>> p = psutil.Process() @@ -919,79 +920,79 @@ Process class (1024, 1024) >>> - Availability: Linux + 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 `__. - 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. + 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 `__. + 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 + Availability: all platforms except OSX and Solaris .. method:: num_ctx_switches() - The number voluntary and involuntary context switches performed by - this process. + The number voluntary and involuntary context switches performed by + this process. .. method:: num_fds() - The number of file descriptors used by this process. + The number of file descriptors used by this process. - Availability: UNIX + Availability: UNIX .. method:: num_handles() - The number of handles used by this process. + The number of handles used by this process. - Availability: Windows + Availability: Windows .. method:: num_threads() - The number of threads used by this process. + The number of threads 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). On OpenBSD this method requires - root access. + Return threads opened by process as a list of namedtuples including thread + id and thread CPU times (user/system). On OpenBSD this method requires + root access. .. method:: cpu_times() - Return a `(user, system, children_user, children_system)` namedtuple - representing the accumulated process time, in seconds (see - `explanation `__). - On Windows and OSX only *user* and *system* are filled, the others are - set to ``0``. - This is similar to - `os.times() `__ - but can be used for any process PID. + Return a `(user, system, children_user, children_system)` namedtuple + representing the accumulated process time, in seconds (see + `explanation `__). + On Windows and OSX only *user* and *system* are filled, the others are + set to ``0``. + This is similar to + `os.times() `__ + but can be used for any process PID. - .. versionchanged:: 4.1.0 return two extra fields: *children_user* and - *children_system*. + .. versionchanged:: + 4.1.0 return two extra fields: *children_user* and *children_system*. .. method:: cpu_percent(interval=None) - Return a float representing the process CPU utilization as a percentage. - The returned value refers to the utilization of a single CPU, i.e. it is - not evenly split between the number of available CPU cores. - 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: + Return a float representing the process CPU utilization as a percentage. + The returned value refers to the utilization of a single CPU, i.e. it is + not evenly split between the number of available CPU cores. + 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() @@ -1004,36 +1005,36 @@ Process class 2.9 >>> - .. note:: - a percentage > 100 is legitimate as it can result from a process with - multiple threads running on different CPU cores. - - .. note:: - the returned value is explcitly **not** split evenly between all CPUs - cores (differently from :func:`psutil.cpu_percent()`). - This means that a busy loop process running on a system with 2 CPU - cores will be reported as having 100% CPU utilization instead of 50%. - This was done in order to be consistent with UNIX's "top" utility - and also to make it easier to identify processes hogging CPU resources - (independently from the number of CPU cores). - It must be noted that in the example above taskmgr.exe on Windows will - report 50% usage instead. - To emulate Windows's taskmgr.exe behavior you can do: - ``p.cpu_percent() / psutil.cpu_count()``. - - .. 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. + .. note:: + a percentage > 100 is legitimate as it can result from a process with + multiple threads running on different CPU cores. + + .. note:: + the returned value is explcitly **not** split evenly between all CPUs + cores (differently from :func:`psutil.cpu_percent()`). + This means that a busy loop process running on a system with 2 CPU + cores will be reported as having 100% CPU utilization instead of 50%. + This was done in order to be consistent with UNIX's "top" utility + and also to make it easier to identify processes hogging CPU resources + (independently from the number of CPU cores). + It must be noted that in the example above taskmgr.exe on Windows will + report 50% usage instead. + To emulate Windows's taskmgr.exe behavior you can do: + ``p.cpu_percent() / psutil.cpu_count()``. + + .. 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 `__. - 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()))``. ``ValueError`` will be raise on set - in case an invalid CPU number is specified. + Get or set process current + `CPU affinity `__. + 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()))``. ``ValueError`` will be raise on set + in case an invalid CPU number is specified. >>> import psutil >>> psutil.cpu_count() @@ -1050,152 +1051,152 @@ Process class >>> p.cpu_affinity(all_cpus) >>> - Availability: Linux, Windows, FreeBSD + Availability: Linux, Windows, FreeBSD - .. versionchanged:: 2.2.0 added support for FreeBSD + .. versionchanged:: 2.2.0 added support for FreeBSD .. method:: memory_info() - Return a namedtuple with variable fields depending on the platform - representing memory information about the process. - The "portable" fields available on all plaforms are `rss` and `vms`. - All numbers are expressed in bytes. - - +---------+---------+-------+---------+------------------------------+ - | Linux | OSX | BSD | Solaris | Windows | - +=========+=========+=======+=========+==============================+ - | rss | rss | rss | rss | rss (alias for ``wset``) | - +---------+---------+-------+---------+------------------------------+ - | vms | vms | vms | vms | vms (alias for ``pagefile``) | - +---------+---------+-------+---------+------------------------------+ - | shared | pfaults | text | | num_page_faults | - +---------+---------+-------+---------+------------------------------+ - | text | pageins | data | | peak_wset | - +---------+---------+-------+---------+------------------------------+ - | lib | | stack | | wset | - +---------+---------+-------+---------+------------------------------+ - | data | | | | peak_paged_pool | - +---------+---------+-------+---------+------------------------------+ - | dirty | | | | paged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | peak_nonpaged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | nonpaged_pool | - +---------+---------+-------+---------+------------------------------+ - | | | | | pagefile | - +---------+---------+-------+---------+------------------------------+ - | | | | | peak_pagefile | - +---------+---------+-------+---------+------------------------------+ - | | | | | private | - +---------+---------+-------+---------+------------------------------+ - - - **rss**: aka "Resident Set Size", this is the non-swapped physical - memory a process has used. - On UNIX it matches "top"'s RES column - (see `doc `__). - On Windows this is an alias for `wset` field and it matches "Mem Usage" - column of taskmgr.exe. - - - **vms**: aka "Virtual Memory Size", this is the total amount of virtual - memory used by the process. - On UNIX it matches "top"'s VIRT column - (see `doc `__). - On Windows this is an alias for `pagefile` field and it matches - "Mem Usage" "VM Size" column of taskmgr.exe. - - - **shared**: *(Linux)* - memory that could be potentially shared with other processes. - This matches "top"'s SHR column - (see `doc `__). - - - **text** *(Linux, BSD)*: - aka TRS (text resident set) the amount of memory devoted to - executable code. This matches "top"'s CODE column - (see `doc `__). - - - **data** *(Linux, BSD)*: - aka DRS (data resident set) the amount of physical memory devoted to - other than executable code. It matches "top"'s DATA column - (see `doc `__). - - - **lib** *(Linux)*: the memory used by shared libraries. - - - **dirty** *(Linux)*: the number of dirty pages. - - For Windows fields rely on - `PROCESS_MEMORY_COUNTERS_EX `__ structure doc. - Example on Linux: + Return a namedtuple with variable fields depending on the platform + representing memory information about the process. + The "portable" fields available on all plaforms are `rss` and `vms`. + All numbers are expressed in bytes. + + +---------+---------+-------+---------+------------------------------+ + | Linux | OSX | BSD | Solaris | Windows | + +=========+=========+=======+=========+==============================+ + | rss | rss | rss | rss | rss (alias for ``wset``) | + +---------+---------+-------+---------+------------------------------+ + | vms | vms | vms | vms | vms (alias for ``pagefile``) | + +---------+---------+-------+---------+------------------------------+ + | shared | pfaults | text | | num_page_faults | + +---------+---------+-------+---------+------------------------------+ + | text | pageins | data | | peak_wset | + +---------+---------+-------+---------+------------------------------+ + | lib | | stack | | wset | + +---------+---------+-------+---------+------------------------------+ + | data | | | | peak_paged_pool | + +---------+---------+-------+---------+------------------------------+ + | dirty | | | | paged_pool | + +---------+---------+-------+---------+------------------------------+ + | | | | | peak_nonpaged_pool | + +---------+---------+-------+---------+------------------------------+ + | | | | | nonpaged_pool | + +---------+---------+-------+---------+------------------------------+ + | | | | | pagefile | + +---------+---------+-------+---------+------------------------------+ + | | | | | peak_pagefile | + +---------+---------+-------+---------+------------------------------+ + | | | | | private | + +---------+---------+-------+---------+------------------------------+ + + - **rss**: aka "Resident Set Size", this is the non-swapped physical + memory a process has used. + On UNIX it matches "top"'s RES column + (see `doc `__). + On Windows this is an alias for `wset` field and it matches "Mem Usage" + column of taskmgr.exe. + + - **vms**: aka "Virtual Memory Size", this is the total amount of virtual + memory used by the process. + On UNIX it matches "top"'s VIRT column + (see `doc `__). + On Windows this is an alias for `pagefile` field and it matches + "Mem Usage" "VM Size" column of taskmgr.exe. + + - **shared**: *(Linux)* + memory that could be potentially shared with other processes. + This matches "top"'s SHR column + (see `doc `__). + + - **text** *(Linux, BSD)*: + aka TRS (text resident set) the amount of memory devoted to + executable code. This matches "top"'s CODE column + (see `doc `__). + + - **data** *(Linux, BSD)*: + aka DRS (data resident set) the amount of physical memory devoted to + other than executable code. It matches "top"'s DATA column + (see `doc `__). + + - **lib** *(Linux)*: the memory used by shared libraries. + + - **dirty** *(Linux)*: the number of dirty pages. + + For Windows fields rely on + `PROCESS_MEMORY_COUNTERS_EX `__ structure doc. + Example on Linux: - >>> import psutil - >>> p = psutil.Process() - >>> p.memory_info() - pmem(rss=15491072, vms=84025344, shared=5206016, text=2555904, lib=0, data=9891840, dirty=0) + >>> import psutil + >>> p = psutil.Process() + >>> p.memory_info() + pmem(rss=15491072, vms=84025344, shared=5206016, text=2555904, lib=0, data=9891840, dirty=0) - .. versionchanged:: - 4.0.0 mutiple fields are returned, not only `rss` and `vms`. + .. versionchanged:: + 4.0.0 mutiple fields are returned, not only `rss` and `vms`. .. method:: memory_info_ex() - Same as :meth:`memory_info` (deprecated). + Same as :meth:`memory_info` (deprecated). - .. warning:: - deprecated in version 4.0.0; use :meth:`memory_info` instead. + .. warning:: + deprecated in version 4.0.0; use :meth:`memory_info` instead. .. method:: memory_full_info() - This method returns the same information as :meth:`memory_info`, plus, on - some platform (Linux, OSX, Windows), also provides additional metrics - (USS, PSS and swap). - The additional metrics provide a better representation of "effective" - process memory consumption (in case of USS) as explained in detail - `here `__. - It does so by passing through the whole process address. - As such it usually requires higher user privileges than - :meth:`memory_info` and is considerably slower. - On platforms where extra fields are not implented this simply returns the - same metrics as :meth:`memory_info`. - - - **uss** *(Linux, OSX, Windows)*: - aka "Unique Set Size", this is the memory which is unique to a process - and which would be freed if the process was terminated right now. - - - **pss** *(Linux)*: aka "Proportional Set Size", is the amount of memory - shared with other processes, accounted in a way that the amount is - divided evenly between the processes that share it. - I.e. if a process has 10 MBs all to itself and 10 MBs shared with - another process its PSS will be 15 MBs. - - - **swap** *(Linux)*: amount of memory that has been swapped out to disk. - - .. note:: - `uss` is probably the most representative metric for determining how - much memory is actually being used by a process. - It represents the amount of memory that would be freed if the process - was terminated right now. - - Example on Linux: - - >>> import psutil - >>> p = psutil.Process() - >>> p.memory_full_info() - pfullmem(rss=10199040, vms=52133888, shared=3887104, text=2867200, lib=0, data=5967872, dirty=0, uss=6545408, pss=6872064, swap=0) - >>> - - See also `scripts/procsmem.py `__ - for an example application. - - .. versionadded:: 4.0.0 + This method returns the same information as :meth:`memory_info`, plus, on + some platform (Linux, OSX, Windows), also provides additional metrics + (USS, PSS and swap). + The additional metrics provide a better representation of "effective" + process memory consumption (in case of USS) as explained in detail + `here `__. + It does so by passing through the whole process address. + As such it usually requires higher user privileges than + :meth:`memory_info` and is considerably slower. + On platforms where extra fields are not implented this simply returns the + same metrics as :meth:`memory_info`. + + - **uss** *(Linux, OSX, Windows)*: + aka "Unique Set Size", this is the memory which is unique to a process + and which would be freed if the process was terminated right now. + + - **pss** *(Linux)*: aka "Proportional Set Size", is the amount of memory + shared with other processes, accounted in a way that the amount is + divided evenly between the processes that share it. + I.e. if a process has 10 MBs all to itself and 10 MBs shared with + another process its PSS will be 15 MBs. + + - **swap** *(Linux)*: amount of memory that has been swapped out to disk. + + .. note:: + `uss` is probably the most representative metric for determining how + much memory is actually being used by a process. + It represents the amount of memory that would be freed if the process + was terminated right now. + + Example on Linux: + + >>> import psutil + >>> p = psutil.Process() + >>> p.memory_full_info() + pfullmem(rss=10199040, vms=52133888, shared=3887104, text=2867200, lib=0, data=5967872, dirty=0, uss=6545408, pss=6872064, swap=0) + >>> + + See also `scripts/procsmem.py `__ + for an example application. + + .. versionadded:: 4.0.0 .. method:: memory_percent(memtype="rss") - Compare process memory to total physical system memory and calculate - process memory utilization as a percentage. - *memtype* argument is a string that dictates what type of process memory - you want to compare against. You can choose between the namedtuple field - names returned by :meth:`memory_info` and :meth:`memory_full_info` - (defaults to ``"rss"``). + Compare process memory to total physical system memory and calculate + process memory utilization as a percentage. + *memtype* argument is a string that dictates what type of process memory + you want to compare against. You can choose between the namedtuple field + names returned by :meth:`memory_info` and :meth:`memory_full_info` + (defaults to ``"rss"``). - .. versionchanged:: 4.0.0 added `memtype` parameter. + .. versionchanged:: 4.0.0 added `memtype` parameter. .. method:: memory_maps(grouped=True) @@ -1252,74 +1253,75 @@ Process class .. method:: children(recursive=False) - Return the children of this process as a list of :Class:`Process` objects, - preemptively checking whether PID has been reused. If recursive is `True` - return all the parent descendants. - Example assuming *A == this process*: - :: + Return the children of this process as a list of :Class:`Process` objects, + preemptively checking whether PID has been reused. If recursive is `True` + return all the parent descendants. + Example assuming *A == this process*: + :: - A ─┐ - │ - ├─ B (child) ─┐ - │ └─ X (grandchild) ─┐ - │ └─ Y (great grandchild) - ├─ C (child) - └─ D (child) + 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 + >>> 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. + 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 following fields: - - - **path**: the absolute file name. - - **fd**: the file descriptor number; on Windows this is always ``-1``. - - **position** (*Linux*): the file (offset) position. - - **mode** (*Linux*): a string indicating how the file was opened, similarly - `open `__'s - ``mode`` argument. Possible values are ``'r'``, ``'w'``, ``'a'``, - ``'r+'`` and ``'a+'``. There's no distinction between files opened in - bynary or text mode (``"b"`` or ``"t"``). - - **flags** (*Linux*): the flags which were passed to the underlying - `os.open `__ C call - when the file was opened (e.g. - `os.O_RDONLY `__, - `os.O_TRUNC `__, - etc). + Return regular files opened by process as a list of namedtuples including + the following fields: + + - **path**: the absolute file name. + - **fd**: the file descriptor number; on Windows this is always ``-1``. + - **position** (*Linux*): the file (offset) position. + - **mode** (*Linux*): a string indicating how the file was opened, similarly + `open `__'s + ``mode`` argument. Possible values are ``'r'``, ``'w'``, ``'a'``, + ``'r+'`` and ``'a+'``. There's no distinction between files opened in + bynary or text mode (``"b"`` or ``"t"``). + - **flags** (*Linux*): the flags which were passed to the underlying + `os.open `__ C call + when the file was opened (e.g. + `os.O_RDONLY `__, + `os.O_TRUNC `__, + etc). - >>> import psutil - >>> f = open('file.ext', 'w') - >>> p = psutil.Process() - >>> p.open_files() - [popenfile(path='/home/giampaolo/svn/psutil/setup.py', fd=3, position=0, mode='r', flags=32768), - popenfile(path='/var/log/monitd', fd=4, position=235542, mode='a', flags=33793)] - - .. 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 - `discussion `_). - - .. warning:: - on BSD this method can return files with a 'null' path due to a kernel - bug hence it's not reliable - (see `issue 595 `_). - - .. versionchanged:: 3.1.0 no longer hangs on Windows. - - .. versionchanged:: 4.1.0 new *position*, *mode* and *flags* fields on - Linux. + >>> import psutil + >>> f = open('file.ext', 'w') + >>> p = psutil.Process() + >>> p.open_files() + [popenfile(path='/home/giampaolo/svn/psutil/setup.py', fd=3, position=0, mode='r', flags=32768), + popenfile(path='/var/log/monitd', fd=4, position=235542, mode='a', flags=33793)] + + .. 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 + `discussion `_). + + .. warning:: + on BSD this method can return files with a 'null' path due to a kernel + bug hence it's not reliable + (see `issue 595 `_). + + .. versionchanged:: + 3.1.0 no longer hangs on Windows. + + .. versionchanged:: + 4.1.0 new *position*, *mode* and *flags* fields on Linux. .. method:: connections(kind="inet") @@ -1354,33 +1356,31 @@ Process class 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 | - +----------------+-----------------------------------------------------+ + +----------------+-----------------------------------------------------+ + | **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: @@ -1396,47 +1396,49 @@ Process class .. 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)``. + 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:: + .. 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 `__ - constants) preemptively checking whether PID has been reused. - On UNIX this is the same as ``os.kill(pid, sig)``. - On Windows only **SIGTERM**, **CTRL_C_EVENT** and **CTRL_BREAK_EVENT** - signals are supported and **SIGTERM** is treated as an alias for - :meth:`kill()`. + Send a signal to process (see + `signal module `__ + constants) preemptively checking whether PID has been reused. + On UNIX this is the same as ``os.kill(pid, sig)``. + On Windows only **SIGTERM**, **CTRL_C_EVENT** and **CTRL_BREAK_EVENT** + signals are supported and **SIGTERM** is treated as an alias for + :meth:`kill()`. - .. versionchanged:: 3.2.0 support for CTRL_C_EVENT and CTRL_BREAK_EVENT signals on Windows was added. + .. versionchanged:: + 3.2.0 support for CTRL_C_EVENT and CTRL_BREAK_EVENT signals on Windows + was added. .. method:: suspend() - Suspend process execution with **SIGSTOP** signal preemptively 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. + Suspend process execution with **SIGSTOP** signal preemptively 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 preemptively 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. + Resume process execution with **SIGCONT** signal preemptively 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 preemptively 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`. + Terminate the process with **SIGTERM** signal preemptively 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() @@ -1448,15 +1450,15 @@ Process class .. method:: wait(timeout=None) - Wait for process termination and if the process is a children of the - current one also return the exit code, else ``None``. On Windows there's - 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()`. + 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 @@ -1480,13 +1482,13 @@ Popen class .. note:: - Unlike `subprocess.Popen `__ - this class preemptively checks wheter PID has been reused on - :meth:`send_signal() `, - :meth:`terminate() ` and - :meth:`kill() ` - so that you can't accidentally terminate another process, fixing - http://bugs.python.org/issue6973. + Unlike `subprocess.Popen `__ + this class preemptively checks wheter PID has been reused on + :meth:`send_signal() `, + :meth:`terminate() ` and + :meth:`kill() ` + so that you can't accidentally terminate another process, fixing + http://bugs.python.org/issue6973. >>> import psutil >>> from subprocess import PIPE @@ -1531,51 +1533,70 @@ Windows services .. method:: name() - The service name. This string is how a service is referenced and can be - passed to :func:`win_service_get` to get a new :class:`WindowsService` - instance. + The service name. This string is how a service is referenced and can be + passed to :func:`win_service_get` to get a new :class:`WindowsService` + instance. .. method:: display_name() - The service display name. The value is cached when this class is - instantiated. + The service display name. The value is cached when this class is + instantiated. .. method:: binpath() - The fully qualified path to the service binary/exe file as a string, - including command line arguments. + The fully qualified path to the service binary/exe file as a string, + including command line arguments. .. method:: username() - The name of the user that owns this service. + The name of the user that owns this service. .. method:: start_type() - A string which can either be `"automatic"`, `"manual"` or `"disabled"`. + A string which can either be `"automatic"`, `"manual"` or `"disabled"`. .. method:: pid() - The process PID, if any, else `None`. This can be passed to - :class:`Process` class to control the service's process. + The process PID, if any, else `None`. This can be passed to + :class:`Process` class to control the service's process. .. method:: status() - Service status as a string, which may be either `"running"`, `"paused"`, - `"start_pending"`, `"pause_pending"`, `"continue_pending"`, - `"stop_pending"` or `"stopped"`. + Service status as a string, which may be either `"running"`, `"paused"`, + `"start_pending"`, `"pause_pending"`, `"continue_pending"`, + `"stop_pending"` or `"stopped"`. .. method:: description() - Service long description. + Service long description. .. method:: as_dict() - Utility method retrieving all the information above as a dictionary. + Utility method retrieving all the information above as a dictionary. .. versionadded:: 4.2.0 Availability: Windows +Example code: + + >>> import psutil + >>> list(psutil.win_service_iter()) + [, + , + , + , + ...] + >>> s = psutil.win_service_get('alg') + >>> s.as_dict() + {'binpath': 'C:\\Windows\\System32\\alg.exe', + 'description': 'Provides support for 3rd party protocol plug-ins for Internet Connection Sharing', + 'display_name': 'Application Layer Gateway Service', + 'name': 'alg', + 'pid': None, + 'start_type': 'manual', + 'status': 'stopped', + 'username': 'NT AUTHORITY\\LocalService'} Constants ========= @@ -1663,7 +1684,8 @@ Constants Availability: Windows - .. versionchanged:: 3.0.0 on Python >= 3.4 these constants are + .. versionchanged:: + 3.0.0 on Python >= 3.4 these constants are `enums `__ instead of a plain integer. @@ -1690,7 +1712,8 @@ Constants Availability: Linux - .. versionchanged:: 3.0.0 on Python >= 3.4 thse constants are + .. versionchanged:: + 3.0.0 on Python >= 3.4 thse constants are `enums `__ instead of a plain integer.