Add *new_only* parameter for process_iter() (#1667)

1 files changed, 15 insertions, 20 deletions

diff --git a/docs/index.rst b/docs/index.rst
index d69e1fac..b1c4ab74 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -855,7 +855,7 @@ Functions
   .. versionchanged::
     5.6.0 PIDs are returned in sorted order
 
-.. function:: process_iter(attrs=None, ad_value=None)
+.. function:: process_iter(attrs=None, ad_value=None, new_only=False)
 
   Return an iterator yielding a :class:`Process` class instance for all running
   processes on the local machine.
@@ -871,25 +871,11 @@ Functions
   the resulting dict is stored as a ``info`` attribute which is attached to the
   returned :class:`Process`  instances.
   If *attrs* is an empty list it will retrieve all process info (slow).
+  If *new_only* is true this function will yield only new processes which
+  appeared since the last time it was called.
   Example usage::
 
     >>> import psutil
-    >>> for proc in psutil.process_iter():
-    ...     try:
-    ...         pinfo = proc.as_dict(attrs=['pid', 'name', 'username'])
-    ...     except psutil.NoSuchProcess:
-    ...         pass
-    ...     else:
-    ...         print(pinfo)
-    ...
-    {'name': 'systemd', 'pid': 1, 'username': 'root'}
-    {'name': 'kthreadd', 'pid': 2, 'username': 'root'}
-    {'name': 'ksoftirqd/0', 'pid': 3, 'username': 'root'}
-    ...
-
-  More compact version using *attrs* parameter::
-
-    >>> import psutil
     >>> for proc in psutil.process_iter(attrs=['pid', 'name', 'username']):
     ...     print(proc.info)
     ...
@@ -909,19 +895,28 @@ Functions
      3: {'name': 'ksoftirqd/0', 'username': 'root'},
      ...}
 
-  Example showing how to filter processes by name::
+  Example showing how to filter processes by name (see also
+  `process filtering <#filtering-and-sorting-processes>`__ section for more
+  examples)::
 
     >>> import psutil
     >>> [p.info for p in psutil.process_iter(attrs=['pid', 'name']) if 'python' in p.info['name']]
     [{'name': 'python3', 'pid': 21947},
      {'name': 'python', 'pid': 23835}]
 
-  See also `process filtering <#filtering-and-sorting-processes>`__ section for
-  more examples.
+  Get new processes only (since last call)::
+
+    >>> import psutil
+    >>> for proc in psutil.process_iter(attrs=['pid', 'name'], new_only=True):
+    ...     print(proc.info)
+    ...
 
   .. versionchanged::
     5.3.0 added "attrs" and "ad_value" parameters.
 
+  .. versionchanged::
+    5.7.0 added "new_only" parameter.
+
 .. function:: pid_exists(pid)
 
   Check whether the given PID exists in the current process list. This is