py2docfx 0.1.20rc2196756__py3-none-any.whl → 0.1.21.dev2246704__py3-none-any.whl

py2docfx/venv/venv1/Lib/site-packages/psutil/__init__.py

@@ -30,7 +30,6 @@ import sys
 import threading
 import time
 
-
 try:
     import pwd
 except ImportError:
@@ -86,7 +85,6 @@ from ._common import debug
 from ._common import memoize_when_activated
 from ._common import wrap_numbers as _wrap_numbers
 
-
 if LINUX:
     # This is public API and it will be retrieved from _pslinux.py
     # via sys.modules.
@@ -207,7 +205,7 @@ if hasattr(_psplatform.Process, "rlimit"):
 AF_LINK = _psplatform.AF_LINK
 
 __author__ = "Giampaolo Rodola'"
-__version__ = "7.0.0"
+__version__ = "7.1.0"
 version_info = tuple(int(num) for num in __version__.split('.'))
 
 _timer = getattr(time, 'monotonic', time.time)
@@ -377,7 +375,11 @@ class Process:
         won't reuse the same PID after such a short period of time
         (0.01 secs). Technically this is inherently racy, but
         practically it should be good enough.
+
+        NOTE: unreliable on FreeBSD and OpenBSD as ctime is subject to
+        system clock updates.
         """
+
         if WINDOWS:
             # Use create_time() fast method in order to speedup
             # `process_iter()`. This means we'll get AccessDenied for
@@ -386,6 +388,11 @@ class Process:
             # https://github.com/giampaolo/psutil/issues/2366#issuecomment-2381646555
             self._create_time = self._proc.create_time(fast_only=True)
             return (self.pid, self._create_time)
+        elif LINUX or NETBSD or OSX:
+            # Use 'monotonic' process starttime since boot to form unique
+            # process identity, since it is stable over changes to system
+            # time.
+            return (self.pid, self._proc.create_time(monotonic=True))
         else:
             return (self.pid, self.create_time())
 
@@ -426,12 +433,12 @@ class Process:
         # on PID and creation time.
         if not isinstance(other, Process):
             return NotImplemented
-        if OPENBSD or NETBSD:  # pragma: no cover
-            # Zombie processes on Open/NetBSD have a creation time of
-            # 0.0. This covers the case when a process started normally
-            # (so it has a ctime), then it turned into a zombie. It's
-            # important to do this because is_running() depends on
-            # __eq__.
+        if OPENBSD or NETBSD or SUNOS:  # pragma: no cover
+            # Zombie processes on Open/NetBSD/illumos/Solaris have a
+            # creation time of 0.0.  This covers the case when a process
+            # started normally (so it has a ctime), then it turned into a
+            # zombie. It's important to do this because is_running()
+            # depends on __eq__.
             pid1, ident1 = self._ident
             pid2, ident2 = other._ident
             if pid1 == pid2:
@@ -593,10 +600,13 @@ class Process:
             return None
         ppid = self.ppid()
         if ppid is not None:
-            ctime = self.create_time()
+            # Get a fresh (non-cached) ctime in case the system clock
+            # was updated. TODO: use a monotonic ctime on platforms
+            # where it's supported.
+            proc_ctime = Process(self.pid).create_time()
             try:
                 parent = Process(ppid)
-                if parent.create_time() <= ctime:
+                if parent.create_time() <= proc_ctime:
                     return parent
                 # ...else ppid has been reused by another process
             except NoSuchProcess:
@@ -765,8 +775,11 @@ class Process:
 
     def create_time(self):
         """The process creation time as a floating point number
-        expressed in seconds since the epoch.
-        The return value is cached after first call.
+        expressed in seconds since the epoch (seconds since January 1,
+        1970, at midnight UTC). The return value, which is cached after
+        first call, is based on the system clock, which means it may be
+        affected by changes such as manual adjustments or time
+        synchronization (e.g. NTP).
         """
         if self._create_time is None:
             self._create_time = self._proc.create_time()
@@ -964,6 +977,10 @@ class Process:
         """
         self._raise_if_pid_reused()
         ppid_map = _ppid_map()
+        # Get a fresh (non-cached) ctime in case the system clock was
+        # updated. TODO: use a monotonic ctime on platforms where it's
+        # supported.
+        proc_ctime = Process(self.pid).create_time()
         ret = []
         if not recursive:
             for pid, ppid in ppid_map.items():
@@ -972,7 +989,7 @@ class Process:
                         child = Process(pid)
                         # if child happens to be older than its parent
                         # (self) it means child's PID has been reused
-                        if self.create_time() <= child.create_time():
+                        if proc_ctime <= child.create_time():
                             ret.append(child)
                     except (NoSuchProcess, ZombieProcess):
                         pass
@@ -998,7 +1015,7 @@ class Process:
                         child = Process(child_pid)
                         # if child happens to be older than its parent
                         # (self) it means child's PID has been reused
-                        intime = self.create_time() <= child.create_time()
+                        intime = proc_ctime <= child.create_time()
                         if intime:
                             ret.append(child)
                             stack.append(child_pid)
@@ -1484,7 +1501,7 @@ def process_iter(attrs=None, ad_value=None):
 
     Every new Process instance is only created once and then cached
     into an internal table which is updated every time this is used.
-    Cache can optionally be cleared via `process_iter.clear_cache()`.
+    Cache can optionally be cleared via `process_iter.cache_clear()`.
 
     The sorting order in which processes are yielded is based on
     their PIDs.
@@ -2352,9 +2369,12 @@ if hasattr(_psplatform, "sensors_battery"):
 
 
 def boot_time():
-    """Return the system boot time expressed in seconds since the epoch."""
-    # Note: we are not caching this because it is subject to
-    # system clock updates.
+    """Return the system boot time expressed in seconds since the epoch
+    (seconds since January 1, 1970, at midnight UTC). The returned
+    value is based on the system clock, which means it may be affected
+    by changes such as manual adjustments or time synchronization (e.g.
+    NTP).
+    """
     return _psplatform.boot_time()
 
 

py2docfx/venv/venv1/Lib/site-packages/psutil/_common.py

@@ -22,7 +22,6 @@ from socket import AF_INET
 from socket import SOCK_DGRAM
 from socket import SOCK_STREAM
 
-
 try:
     from socket import AF_INET6
 except ImportError:
@@ -409,7 +408,7 @@ def memoize(fun):
         except KeyError:
             try:
                 ret = cache[key] = fun(*args, **kwargs)
-            except Exception as err:  # noqa: BLE001
+            except Exception as err:
                 raise err from None
             return ret
 
@@ -458,14 +457,14 @@ def memoize_when_activated(fun):
             # case 2: we never entered oneshot() ctx
             try:
                 return fun(self)
-            except Exception as err:  # noqa: BLE001
+            except Exception as err:
                 raise err from None
         except KeyError:
             # case 3: we entered oneshot() ctx but there's no cache
             # for this entry yet
             try:
                 ret = fun(self)
-            except Exception as err:  # noqa: BLE001
+            except Exception as err:
                 raise err from None
             try:
                 self._cache[fun] = ret
@@ -523,7 +522,6 @@ def path_exists_strict(path):
         return True
 
 
-@memoize
 def supports_ipv6():
     """Return True if IPv6 is supported on this platform."""
     if not socket.has_ipv6 or AF_INET6 is None:

py2docfx/venv/venv1/Lib/site-packages/psutil/_psaix.py

@@ -29,7 +29,6 @@ from ._common import get_procfs_path
 from ._common import memoize_when_activated
 from ._common import usage_percent
 
-
 __extra__all__ = ["PROCFS_PATH"]
 
 
@@ -279,7 +278,7 @@ def boot_time():
 def users():
     """Return currently connected users as a list of namedtuples."""
     retlist = []
-    rawlist = cext.users()
+    rawlist = cext_posix.users()
     localhost = (':0.0', ':0')
     for item in rawlist:
         user, tty, hostname, tstamp, user_process, pid = item

py2docfx/venv/venv1/Lib/site-packages/psutil/_psbsd.py

@@ -29,7 +29,6 @@ from ._common import memoize
 from ._common import memoize_when_activated
 from ._common import usage_percent
 
-
 __extra__all__ = []
 
 
@@ -98,10 +97,7 @@ TCP_STATUSES = {
 PAGESIZE = cext_posix.getpagesize()
 AF_LINK = cext_posix.AF_LINK
 
-HAS_PER_CPU_TIMES = hasattr(cext, "per_cpu_times")
 HAS_PROC_NUM_THREADS = hasattr(cext, "proc_num_threads")
-HAS_PROC_OPEN_FILES = hasattr(cext, 'proc_open_files')
-HAS_PROC_NUM_FDS = hasattr(cext, 'proc_num_fds')
 
 kinfo_proc_map = dict(
     ppid=0,
@@ -240,36 +236,14 @@ def cpu_times():
     return scputimes(user, nice, system, idle, irq)
 
 
-if HAS_PER_CPU_TIMES:
-
-    def per_cpu_times():
-        """Return system CPU times as a namedtuple."""
-        ret = []
-        for cpu_t in cext.per_cpu_times():
-            user, nice, system, idle, irq = cpu_t
-            item = scputimes(user, nice, system, idle, irq)
-            ret.append(item)
-        return ret
-
-else:
-    # XXX
-    # Ok, this is very dirty.
-    # On FreeBSD < 8 we cannot gather per-cpu information, see:
-    # https://github.com/giampaolo/psutil/issues/226
-    # If num cpus > 1, on first call we return single cpu times to avoid a
-    # crash at psutil import time.
-    # Next calls will fail with NotImplementedError
-    def per_cpu_times():
-        """Return system CPU times as a namedtuple."""
-        if cpu_count_logical() == 1:
-            return [cpu_times()]
-        if per_cpu_times.__called__:
-            msg = "supported only starting from FreeBSD 8"
-            raise NotImplementedError(msg)
-        per_cpu_times.__called__ = True
-        return [cpu_times()]
-
-    per_cpu_times.__called__ = False
+def per_cpu_times():
+    """Return system CPU times as a namedtuple."""
+    ret = []
+    for cpu_t in cext.per_cpu_times():
+        user, nice, system, idle, irq = cpu_t
+        item = scputimes(user, nice, system, idle, irq)
+        ret.append(item)
+    return ret
 
 
 def cpu_count_logical():
@@ -505,15 +479,36 @@ def boot_time():
     return cext.boot_time()
 
 
+if NETBSD:
+
+    try:
+        INIT_BOOT_TIME = boot_time()
+    except Exception as err:  # noqa: BLE001
+        # Don't want to crash at import time.
+        debug(f"ignoring exception on import: {err!r}")
+        INIT_BOOT_TIME = 0
+
+    def adjust_proc_create_time(ctime):
+        """Account for system clock updates."""
+        if INIT_BOOT_TIME == 0:
+            return ctime
+
+        diff = INIT_BOOT_TIME - boot_time()
+        if diff == 0 or abs(diff) < 1:
+            return ctime
+
+        debug("system clock was updated; adjusting process create_time()")
+        if diff < 0:
+            return ctime - diff
+        return ctime + diff
+
+
 def users():
     """Return currently connected users as a list of namedtuples."""
     retlist = []
-    rawlist = cext.users()
+    rawlist = cext.users() if OPENBSD else cext_posix.users()
     for item in rawlist:
         user, tty, hostname, tstamp, pid = item
-        if pid == -1:
-            assert OPENBSD
-            pid = None
         if tty == '~':
             continue  # reboot or shutdown
         nt = _common.suser(user, tty or None, hostname, tstamp, pid)
@@ -779,13 +774,17 @@ class Process:
     memory_full_info = memory_info
 
     @wrap_exceptions
-    def create_time(self):
-        return self.oneshot()[kinfo_proc_map['create_time']]
+    def create_time(self, monotonic=False):
+        ctime = self.oneshot()[kinfo_proc_map['create_time']]
+        if NETBSD and not monotonic:
+            # NetBSD: ctime subject to system clock updates.
+            ctime = adjust_proc_create_time(ctime)
+        return ctime
 
     @wrap_exceptions
     def num_threads(self):
         if HAS_PROC_NUM_THREADS:
-            # FreeBSD
+            # FreeBSD / NetBSD
             return cext.proc_num_threads(self.pid)
         else:
             return len(self.threads())
@@ -870,14 +869,7 @@ class Process:
         # it into None
         if OPENBSD and self.pid == 0:
             return ""  # ...else it would raise EINVAL
-        elif NETBSD or HAS_PROC_OPEN_FILES:
-            # FreeBSD < 8 does not support functions based on
-            # kinfo_getfile() and kinfo_getvmmap()
-            return cext.proc_cwd(self.pid)
-        else:
-            raise NotImplementedError(
-                "supported only starting from FreeBSD 8" if FREEBSD else ""
-            )
+        return cext.proc_cwd(self.pid)
 
     nt_mmap_grouped = namedtuple(
         'mmap', 'path rss, private, ref_count, shadow_count'
@@ -886,36 +878,19 @@ class Process:
         'mmap', 'addr, perms path rss, private, ref_count, shadow_count'
     )
 
-    def _not_implemented(self):
-        raise NotImplementedError
-
-    # FreeBSD < 8 does not support functions based on kinfo_getfile()
-    # and kinfo_getvmmap()
-    if HAS_PROC_OPEN_FILES:
-
-        @wrap_exceptions
-        def open_files(self):
-            """Return files opened by process as a list of namedtuples."""
-            rawlist = cext.proc_open_files(self.pid)
-            return [_common.popenfile(path, fd) for path, fd in rawlist]
-
-    else:
-        open_files = _not_implemented
-
-    # FreeBSD < 8 does not support functions based on kinfo_getfile()
-    # and kinfo_getvmmap()
-    if HAS_PROC_NUM_FDS:
-
-        @wrap_exceptions
-        def num_fds(self):
-            """Return the number of file descriptors opened by this process."""
-            ret = cext.proc_num_fds(self.pid)
-            if NETBSD:
-                self._assert_alive()
-            return ret
+    @wrap_exceptions
+    def open_files(self):
+        """Return files opened by process as a list of namedtuples."""
+        rawlist = cext.proc_open_files(self.pid)
+        return [_common.popenfile(path, fd) for path, fd in rawlist]
 
-    else:
-        num_fds = _not_implemented
+    @wrap_exceptions
+    def num_fds(self):
+        """Return the number of file descriptors opened by this process."""
+        ret = cext.proc_num_fds(self.pid)
+        if NETBSD:
+            self._assert_alive()
+        return ret
 
     # --- FreeBSD only APIs
 

py2docfx/venv/venv1/Lib/site-packages/psutil/_pslinux.py

@@ -47,7 +47,6 @@ from ._common import path_exists_strict
 from ._common import supports_ipv6
 from ._common import usage_percent
 
-
 # fmt: off
 __extra__all__ = [
     'PROCFS_PATH',
@@ -81,8 +80,8 @@ HAS_CPU_AFFINITY = hasattr(cext, "proc_cpu_affinity_get")
 # Number of clock ticks per second
 CLOCK_TICKS = os.sysconf("SC_CLK_TCK")
 PAGESIZE = cext_posix.getpagesize()
-BOOT_TIME = None  # set later
 LITTLE_ENDIAN = sys.byteorder == 'little'
+UNSET = object()
 
 # "man iostat" states that sectors are equivalent with blocks and have
 # a size of 512 bytes. Despite this value can be queried at runtime
@@ -421,12 +420,6 @@ def virtual_memory():
     except KeyError:
         slab = 0
 
-    used = total - free - cached - buffers
-    if used < 0:
-        # May be symptomatic of running within a LCX container where such
-        # values will be dramatically distorted over those of the host.
-        used = total - free
-
     # - starting from 4.4.0 we match free's "available" column.
     #   Before 4.4.0 we calculated it as (free + buffers + cached)
     #   which matched htop.
@@ -457,6 +450,8 @@ def virtual_memory():
         #     24fd2605c51fccc375ab0287cec33aa767f06718/proc/sysinfo.c#L764
         avail = free
 
+    used = total - avail
+
     percent = usage_percent((total - avail), total, round_=1)
 
     # Warn about missing metrics which are set to 0.
@@ -1525,7 +1520,7 @@ def sensors_battery():
         secsleft = _common.POWER_TIME_UNLIMITED
     elif energy_now is not None and power_now is not None:
         try:
-            secsleft = int(energy_now / power_now * 3600)
+            secsleft = int(energy_now / abs(power_now) * 3600)
         except ZeroDivisionError:
             secsleft = _common.POWER_TIME_UNKNOWN
     elif time_to_empty is not None:
@@ -1546,7 +1541,7 @@ def sensors_battery():
 def users():
     """Return currently connected users as a list of namedtuples."""
     retlist = []
-    rawlist = cext.users()
+    rawlist = cext_posix.users()
     for item in rawlist:
         user, tty, hostname, tstamp, pid = item
         nt = _common.suser(user, tty or None, hostname, tstamp, pid)
@@ -1556,14 +1551,11 @@ def users():
 
 def boot_time():
     """Return the system boot time expressed in seconds since the epoch."""
-    global BOOT_TIME
     path = f"{get_procfs_path()}/stat"
     with open_binary(path) as f:
         for line in f:
             if line.startswith(b'btime'):
-                ret = float(line.strip().split()[1])
-                BOOT_TIME = ret
-                return ret
+                return float(line.strip().split()[1])
         msg = f"line 'btime' not found in {path}"
         raise RuntimeError(msg)
 
@@ -1623,9 +1615,9 @@ def ppid_map():
             with open_binary(f"{procfs_path}/{pid}/stat") as f:
                 data = f.read()
         except (FileNotFoundError, ProcessLookupError):
-            # Note: we should be able to access /stat for all processes
-            # aka it's unlikely we'll bump into EPERM, which is good.
             pass
+        except PermissionError as err:
+            raise AccessDenied(pid) from err
         else:
             rpar = data.rfind(b')')
             dset = data[rpar + 2 :].split()
@@ -1664,12 +1656,20 @@ def wrap_exceptions(fun):
 class Process:
     """Linux process implementation."""
 
-    __slots__ = ["_cache", "_name", "_ppid", "_procfs_path", "pid"]
+    __slots__ = [
+        "_cache",
+        "_ctime",
+        "_name",
+        "_ppid",
+        "_procfs_path",
+        "pid",
+    ]
 
     def __init__(self, pid):
         self.pid = pid
         self._name = None
         self._ppid = None
+        self._ctime = None
         self._procfs_path = get_procfs_path()
 
     def _is_zombie(self):
@@ -1698,6 +1698,22 @@ class Process:
         # incorrect or incomplete result.
         os.stat(f"{self._procfs_path}/{self.pid}")
 
+    def _readlink(self, path, fallback=UNSET):
+        # * https://github.com/giampaolo/psutil/issues/503
+        #   os.readlink('/proc/pid/exe') may raise ESRCH (ProcessLookupError)
+        #   instead of ENOENT (FileNotFoundError) when it races.
+        # * ENOENT may occur also if the path actually exists if PID is
+        #   a low PID (~0-20 range).
+        # * https://github.com/giampaolo/psutil/issues/2514
+        try:
+            return readlink(path)
+        except (FileNotFoundError, ProcessLookupError):
+            if os.path.lexists(f"{self._procfs_path}/{self.pid}"):
+                self._raise_if_zombie()
+                if fallback is not UNSET:
+                    return fallback
+            raise
+
     @wrap_exceptions
     @memoize_when_activated
     def _parse_stat_file(self):
@@ -1770,16 +1786,9 @@ class Process:
 
     @wrap_exceptions
     def exe(self):
-        try:
-            return readlink(f"{self._procfs_path}/{self.pid}/exe")
-        except (FileNotFoundError, ProcessLookupError):
-            self._raise_if_zombie()
-            # no such file error; might be raised also if the
-            # path actually exists for system processes with
-            # low pids (about 0-20)
-            if os.path.lexists(f"{self._procfs_path}/{self.pid}"):
-                return ""
-            raise
+        return self._readlink(
+            f"{self._procfs_path}/{self.pid}/exe", fallback=""
+        )
 
     @wrap_exceptions
     def cmdline(self):
@@ -1880,15 +1889,21 @@ class Process:
         return _psposix.wait_pid(self.pid, timeout, self._name)
 
     @wrap_exceptions
-    def create_time(self):
-        ctime = float(self._parse_stat_file()['create_time'])
-        # According to documentation, starttime is in field 21 and the
-        # unit is jiffies (clock ticks).
-        # We first divide it for clock ticks and then add uptime returning
-        # seconds since the epoch.
-        # Also use cached value if available.
-        bt = BOOT_TIME or boot_time()
-        return (ctime / CLOCK_TICKS) + bt
+    def create_time(self, monotonic=False):
+        # The 'starttime' field in /proc/[pid]/stat is expressed in
+        # jiffies (clock ticks per second), a relative value which
+        # represents the number of clock ticks that have passed since
+        # the system booted until the process was created. It never
+        # changes and is unaffected by system clock updates.
+        if self._ctime is None:
+            self._ctime = (
+                float(self._parse_stat_file()['create_time']) / CLOCK_TICKS
+            )
+        if monotonic:
+            return self._ctime
+        # Add the boot time, returning time expressed in seconds since
+        # the epoch. This is subject to system clock updates.
+        return self._ctime + boot_time()
 
     @wrap_exceptions
     def memory_info(self):
@@ -2001,7 +2016,7 @@ class Process:
                     else:
                         try:
                             data[fields[0]] = int(fields[1]) * 1024
-                        except ValueError:
+                        except (ValueError, IndexError):
                             if fields[0].startswith(b'VmFlags:'):
                                 # see issue #369
                                 continue
@@ -2054,7 +2069,9 @@ class Process:
 
     @wrap_exceptions
     def cwd(self):
-        return readlink(f"{self._procfs_path}/{self.pid}/cwd")
+        return self._readlink(
+            f"{self._procfs_path}/{self.pid}/cwd", fallback=""
+        )
 
     @wrap_exceptions
     def num_ctx_switches(

py2docfx/venv/venv1/Lib/site-packages/psutil/_psosx.py

@@ -18,12 +18,12 @@ from ._common import NoSuchProcess
 from ._common import ZombieProcess
 from ._common import conn_tmap
 from ._common import conn_to_ntuple
+from ._common import debug
 from ._common import isfile_strict
 from ._common import memoize_when_activated
 from ._common import parse_environ_block
 from ._common import usage_percent
 
-
 __extra__all__ = []
 
 
@@ -170,14 +170,16 @@ def cpu_stats():
     )
 
 
-def cpu_freq():
-    """Return CPU frequency.
-    On macOS per-cpu frequency is not supported.
-    Also, the returned frequency never changes, see:
-    https://arstechnica.com/civis/viewtopic.php?f=19&t=465002.
-    """
-    curr, min_, max_ = cext.cpu_freq()
-    return [_common.scpufreq(curr, min_, max_)]
+if cext.has_cpu_freq():  # not always available on ARM64
+
+    def cpu_freq():
+        """Return CPU frequency.
+        On macOS per-cpu frequency is not supported.
+        Also, the returned frequency never changes, see:
+        https://arstechnica.com/civis/viewtopic.php?f=19&t=465002.
+        """
+        curr, min_, max_ = cext.cpu_freq()
+        return [_common.scpufreq(curr, min_, max_)]
 
 
 # =====================================================================
@@ -288,10 +290,33 @@ def boot_time():
     return cext.boot_time()
 
 
+try:
+    INIT_BOOT_TIME = boot_time()
+except Exception as err:  # noqa: BLE001
+    # Don't want to crash at import time.
+    debug(f"ignoring exception on import: {err!r}")
+    INIT_BOOT_TIME = 0
+
+
+def adjust_proc_create_time(ctime):
+    """Account for system clock updates."""
+    if INIT_BOOT_TIME == 0:
+        return ctime
+
+    diff = INIT_BOOT_TIME - boot_time()
+    if diff == 0 or abs(diff) < 1:
+        return ctime
+
+    debug("system clock was updated; adjusting process create_time()")
+    if diff < 0:
+        return ctime - diff
+    return ctime + diff
+
+
 def users():
     """Return currently connected users as a list of namedtuples."""
     retlist = []
-    rawlist = cext.users()
+    rawlist = cext_posix.users()
     for item in rawlist:
         user, tty, hostname, tstamp, pid = item
         if tty == '~':
@@ -470,8 +495,11 @@ class Process:
         )
 
     @wrap_exceptions
-    def create_time(self):
-        return self._get_kinfo_proc()[kinfo_proc_map['ctime']]
+    def create_time(self, monotonic=False):
+        ctime = self._get_kinfo_proc()[kinfo_proc_map['ctime']]
+        if not monotonic:
+            ctime = adjust_proc_create_time(ctime)
+        return ctime
 
     @wrap_exceptions
     def num_ctx_switches(self):