diff options
| -rw-r--r-- | psutil/_psbsd.py | 8 | ||||
| -rw-r--r-- | psutil/_pslinux.py | 32 | ||||
| -rw-r--r-- | psutil/_psosx.py | 3 | ||||
| -rw-r--r-- | psutil/_psposix.py | 3 | ||||
| -rw-r--r-- | psutil/_pssunos.py | 6 | ||||
| -rw-r--r-- | psutil/_pswindows.py | 17 |
6 files changed, 57 insertions, 12 deletions
diff --git a/psutil/_psbsd.py b/psutil/_psbsd.py index fb141cf2..72ef71e8 100644 --- a/psutil/_psbsd.py +++ b/psutil/_psbsd.py @@ -229,6 +229,7 @@ else: # 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__: @@ -278,6 +279,7 @@ else: def cpu_stats(): + """Return various CPU stats as a named tuple.""" if FREEBSD: # Note: the C ext is returning some metrics we are not exposing: # traps. @@ -353,6 +355,7 @@ def net_if_stats(): def net_connections(kind): + """System-wide network connections.""" if OPENBSD: ret = [] for pid in pids(): @@ -403,6 +406,7 @@ def net_connections(kind): if FREEBSD: def sensors_battery(): + """Return battery info.""" percent, minsleft, power_plugged = cext.sensors_battery() power_plugged = power_plugged == 1 if power_plugged: @@ -425,6 +429,7 @@ def boot_time(): def users(): + """Return currently connected users as a list of namedtuples.""" retlist = [] rawlist = cext.users() for item in rawlist: @@ -454,6 +459,7 @@ def _pid_0_exists(): def pids(): + """Returns a list of PIDs currently running on the system.""" ret = cext.pids() if OPENBSD and (0 not in ret) and _pid_0_exists(): # On OpenBSD the kernel does not return PID 0 (neither does @@ -464,6 +470,7 @@ def pids(): if OPENBSD or NETBSD: def pid_exists(pid): + """Return True if pid exists.""" exists = _psposix.pid_exists(pid) if not exists: # We do this because _psposix.pid_exists() lies in case of @@ -502,6 +509,7 @@ def wrap_exceptions(fun): @contextlib.contextmanager def wrap_exceptions_procfs(inst): + """Same as above, for routines relying on reading /proc fs.""" try: yield except EnvironmentError as err: diff --git a/psutil/_pslinux.py b/psutil/_pslinux.py index 8fc0bb6d..4df43ea3 100644 --- a/psutil/_pslinux.py +++ b/psutil/_pslinux.py @@ -210,6 +210,7 @@ else: def get_procfs_path(): + """Return updated psutil.PROCFS_PATH constant.""" return sys.modules['psutil'].PROCFS_PATH @@ -234,6 +235,9 @@ def readlink(path): def file_flags_to_mode(flags): + """Convert file's open() flags into a readable string. + Used by Process.open_files(). + """ modes_map = {os.O_RDONLY: 'r', os.O_WRONLY: 'w', os.O_RDWR: 'w+'} mode = modes_map[flags & (os.O_RDONLY | os.O_WRONLY | os.O_RDWR)] if flags & os.O_APPEND: @@ -244,22 +248,25 @@ def file_flags_to_mode(flags): def get_sector_size(partition): + """Return the sector size of a partition. + Used by disk_io_counters(). + """ try: with open("/sys/block/%s/queue/hw_sector_size" % partition, "rt") as f: return int(f.read()) except (IOError, ValueError): # man iostat states that sectors are equivalent with blocks and - # have a size of 512 bytes since 2.4 kernels. This value is - # needed to calculate the amount of disk I/O in bytes. + # have a size of 512 bytes since 2.4 kernels. return 512 @memoize def set_scputimes_ntuple(procfs_path): - """Return a namedtuple of variable fields depending on the - CPU times available on this Linux kernel version which may be: + """Set a namedtuple of variable fields depending on the CPU times + available on this Linux kernel version which may be: (user, nice, system, idle, iowait, irq, softirq, [steal, [guest, [guest_nice]]]) + Used by cpu_times() function. """ global scputimes with open_binary('%s/stat' % procfs_path) as f: @@ -276,11 +283,14 @@ def set_scputimes_ntuple(procfs_path): # Linux >= 3.2.0 fields.append('guest_nice') scputimes = namedtuple('scputimes', fields) - return scputimes def cat(fname, fallback=_DEFAULT, binary=True): - """Return file content.""" + """Return file content. + fallback: the value returned in case the file does not exist or + cannot be read + binary: whether to open the file in binary or text mode. + """ try: with open_binary(fname) if binary else open_text(fname) as f: return f.read().strip() @@ -291,7 +301,7 @@ def cat(fname, fallback=_DEFAULT, binary=True): try: - scputimes = set_scputimes_ntuple("/proc") + set_scputimes_ntuple("/proc") except Exception: # Don't want to crash at import time. traceback.print_exc() @@ -469,6 +479,7 @@ def virtual_memory(): def swap_memory(): + """Return swap memory metrics.""" _, _, _, _, total, free, unit_multiplier = cext.linux_sysinfo() total *= unit_multiplier free *= unit_multiplier @@ -602,6 +613,7 @@ def cpu_count_physical(): def cpu_stats(): + """Return various CPU stats as a named tuple.""" with open_binary('%s/stat' % get_procfs_path()) as f: ctx_switches = None interrupts = None @@ -624,6 +636,10 @@ def cpu_stats(): if os.path.exists("/sys/devices/system/cpu/cpufreq"): def cpu_freq(): + """Return frequency metrics for all CPUs. + Contrarily to other OSes, Linux updates these values in + real-time. + """ # scaling_* files seem preferable to cpuinfo_*, see: # http://unix.stackexchange.com/a/87537/168884 ret = [] @@ -1031,7 +1047,7 @@ def disk_io_counters(): def disk_partitions(all=False): - """Return mounted disk partitions as a list of namedtuples""" + """Return mounted disk partitions as a list of namedtuples.""" fstypes = set() with open_text("%s/filesystems" % get_procfs_path()) as f: for line in f: diff --git a/psutil/_psosx.py b/psutil/_psosx.py index f7adb43a..f22ef2fb 100644 --- a/psutil/_psosx.py +++ b/psutil/_psosx.py @@ -185,6 +185,7 @@ disk_io_counters = cext.disk_io_counters def disk_partitions(all=False): + """Return mounted disk partitions as a list of namedtuples.""" retlist = [] partitions = cext.disk_partitions() for partition in partitions: @@ -209,6 +210,7 @@ net_if_addrs = cext_posix.net_if_addrs def net_connections(kind='inet'): + """System-wide network connections.""" # Note: on OSX this will fail with AccessDenied unless # the process is owned by root. ret = [] @@ -250,6 +252,7 @@ def boot_time(): def users(): + """Return currently connected users as a list of namedtuples.""" retlist = [] rawlist = cext.users() for item in rawlist: diff --git a/psutil/_psposix.py b/psutil/_psposix.py index 6debdb32..6ed7694a 100644 --- a/psutil/_psposix.py +++ b/psutil/_psposix.py @@ -169,6 +169,9 @@ def disk_usage(path): @memoize def get_terminal_map(): + """Get a map of device-id -> path as a dict. + Used by Process.terminal() + """ ret = {} ls = glob.glob('/dev/tty*') + glob.glob('/dev/pts/*') for name in ls: diff --git a/psutil/_pssunos.py b/psutil/_pssunos.py index e6796bf9..41547a8f 100644 --- a/psutil/_pssunos.py +++ b/psutil/_pssunos.py @@ -102,6 +102,7 @@ TimeoutExpired = None def get_procfs_path(): + """Return updated psutil.PROCFS_PATH constant.""" return sys.modules['psutil'].PROCFS_PATH @@ -111,7 +112,8 @@ def get_procfs_path(): def virtual_memory(): - # we could have done this with kstat, but imho this is good enough + """Report virtual memory metrics.""" + # we could have done this with kstat, but IMHO this is good enough total = os.sysconf('SC_PHYS_PAGES') * PAGE_SIZE # note: there's no difference on Solaris free = avail = os.sysconf('SC_AVPHYS_PAGES') * PAGE_SIZE @@ -121,6 +123,7 @@ def virtual_memory(): def swap_memory(): + """Report swap memory metrics.""" sin, sout = cext.swap_mem() # XXX # we are supposed to get total/free by doing so: @@ -184,6 +187,7 @@ def cpu_count_physical(): def cpu_stats(): + """Return various CPU stats as a named tuple.""" ctx_switches, interrupts, syscalls, traps = cext.cpu_stats() soft_interrupts = 0 return _common.scpustats(ctx_switches, interrupts, soft_interrupts, diff --git a/psutil/_pswindows.py b/psutil/_pswindows.py index 53f57a7a..271b4c7d 100644 --- a/psutil/_pswindows.py +++ b/psutil/_pswindows.py @@ -174,9 +174,11 @@ TimeoutExpired = None @lru_cache(maxsize=512) def convert_dos_path(s): - # convert paths using native DOS format like: - # "\Device\HarddiskVolume1\Windows\systemew\file.txt" - # into: "C:\Windows\systemew\file.txt" + """Convert paths using native DOS format like: + "\Device\HarddiskVolume1\Windows\systemew\file.txt" + into: + "C:\Windows\systemew\file.txt" + """ if PY3 and not isinstance(s, str): s = s.decode('utf8') rawdrive = '\\'.join(s.split('\\')[:3]) @@ -185,6 +187,9 @@ def convert_dos_path(s): def py2_strencode(s, encoding=sys.getfilesystemencoding()): + """Encode a string in the given encoding. Falls back on returning + the string as is if it can't be encoded. + """ if PY3 or isinstance(s, str): return s else: @@ -333,6 +338,7 @@ def net_connections(kind, _pid=-1): def net_if_stats(): + """Get NIC stats (isup, duplex, speed, mtu).""" ret = cext.net_if_stats() for name, items in ret.items(): name = py2_strencode(name) @@ -344,11 +350,15 @@ def net_if_stats(): def net_io_counters(): + """Return network I/O statistics for every network interface + installed on the system as a dict of raw tuples. + """ ret = cext.net_io_counters() return dict([(py2_strencode(k), v) for k, v in ret.items()]) def net_if_addrs(): + """Return the addresses associated to each NIC.""" ret = [] for items in cext.net_if_addrs(): items = list(items) @@ -363,6 +373,7 @@ def net_if_addrs(): def sensors_battery(): + """Return battery information.""" # For constants meaning see: # https://msdn.microsoft.com/en-us/library/windows/desktop/ # aa373232(v=vs.85).aspx |