Ifconfig 376

docs/index.rst

@@ -200,7 +200,7 @@ Memory
   * **total**: total swap memory in bytes
   * **used**: used swap memory in bytes
   * **free**: free swap memory in bytes
-  * **percent**: the percentage usage
+  * **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
@@ -403,6 +403,47 @@ Network
 
   .. 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_PACKET: 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_PACKET: 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*
+
 
 Other system info
 -----------------
@@ -1255,3 +1296,11 @@ Constants
   `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*

examples/ifconfig.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python
+
+# Copyright (c) 2009, Giampaolo Rodola'. All rights reserved.
+# Use of this source code is governed by a BSD-style license that can be
+# found in the LICENSE file.
+
+"""
+A clone of 'ifconfig' on UNIX.
+
+$ python examples/ifconfig.py
+lo:
+    IPv4     address   : 127.0.0.1
+             broadcast : 127.0.0.1
+             netmask   : 255.0.0.0
+    IPv6     address   : ::1
+             netmask   : ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
+    HWADDR   address   : 00:00:00:00:00:00
+             broadcast : 00:00:00:00:00:00
+
+wlan0:
+    IPv4     address   : 192.168.1.3
+             broadcast : 192.168.1.255
+             netmask   : 255.255.255.0
+    IPv6     address   : fe80::c685:8ff:fe45:641%wlan0
+             netmask   : ffff:ffff:ffff:ffff::
+    HWADDR   address   : c4:85:08:45:06:41
+             broadcast : ff:ff:ff:ff:ff:ff
+
+docker0:
+    IPv4     address   : 172.17.42.1
+             broadcast : 172.17.42.1
+             netmask   : 255.255.0.0
+    IPv6     address   : fe80::ac6d:3aff:fe0d:a19c%docker0
+             netmask   : ffff:ffff:ffff:ffff::
+    HWADDR   address   : ae:6d:3a:0d:a1:9c
+             broadcast : ff:ff:ff:ff:ff:ff
+"""
+
+from __future__ import print_function
+import socket
+
+import psutil
+
+
+af_map = {
+    socket.AF_INET: 'IPv4',
+    socket.AF_INET6: 'IPv6',
+    psutil.AF_LINK: 'HWADDR',
+}
+
+
+def main():
+    for nic, addrs in psutil.net_if_addrs().items():
+        print("%s:" % (nic))
+        for addr in addrs:
+            print("    %-8s" % af_map.get(addr.family, addr.family), end="")
+            print(" address   : %s" % addr.address)
+            if addr.broadcast:
+                print("             broadcast : %s" % addr.broadcast)
+            if addr.netmask:
+                print("             netmask   : %s" % addr.netmask)
+        print("")
+
+
+if __name__ == '__main__':
+    main()

psutil/__init__.py

@@ -11,6 +11,7 @@
 """
 
 from __future__ import division
+
 import collections
 import errno
 import functools
@@ -31,7 +32,9 @@
 from ._common import (deprecated_method as _deprecated_method,
                       deprecated as _deprecated,
                       sdiskio as _nt_sys_diskio,
-                      snetio as _nt_sys_netio)
+                      snetio as _nt_sys_netio,
+                      snic as _nt_snic,
+                      )
 
 from ._common import (STATUS_RUNNING,  # NOQA
                       STATUS_SLEEPING,
@@ -144,20 +147,22 @@
     "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",
+    "AF_LINK",
     # classes
     "Process", "Popen",
     # functions
     "pid_exists", "pids", "process_iter", "wait_procs",             # proc
     "virtual_memory", "swap_memory",                                # memory
     "cpu_times", "cpu_percent", "cpu_times_percent", "cpu_count",   # cpu
-    "net_io_counters", "net_connections",                           # network
+    "net_io_counters", "net_connections", "net_if_addrs",           # network
     "disk_io_counters", "disk_partitions", "disk_usage",            # disk
     "users", "boot_time",                                           # others
 ]
 __all__.extend(_psplatform.__extra__all__)
 __author__ = "Giampaolo Rodola'"
 __version__ = "3.0.0"
 version_info = tuple([int(num) for num in __version__.split('.')])
+AF_LINK = _psplatform.AF_LINK
 _TOTAL_PHYMEM = None
 _POSIX = os.name == 'posix'
 _WINDOWS = os.name == 'nt'
@@ -1814,6 +1819,40 @@ def net_connections(kind='inet'):
     return _psplatform.net_connections(kind)
 
 
+def 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 socket.AF_INET, socket.AF_INET6 or
+    psutil.AF_LINK, which refers to a MAC address.
+    'address' is the primary address, 'netmask' and 'broadcast'
+    may be None.
+    Note: you can have more than one address of the same family
+    associated with each interface.
+    """
+    has_enums = sys.version_info >= (3, 4)
+    if has_enums:
+        import socket
+    rawlist = _psplatform.net_if_addrs()
+    rawlist.sort(key=lambda x: x[1])  # sort by family
+    ret = collections.defaultdict(list)
+    for name, fam, addr, mask, broadcast in rawlist:
+        if has_enums:
+            try:
+                fam = socket.AddressFamily(fam)
+            except ValueError:
+                pass
+        ret[name].append(_nt_snic(fam, addr, mask, broadcast))
+    return dict(ret)
+
+
 # =====================================================================
 # --- other system related functions
 # =====================================================================

psutil/_common.py

@@ -238,6 +238,8 @@ def socktype_to_enum(num):
 # psutil.net_connections()
 sconn = namedtuple('sconn', ['fd', 'family', 'type', 'laddr', 'raddr',
                              'status', 'pid'])
+# psutil.net_if_addrs()
+snic = namedtuple('snic', ['family', 'address', 'netmask', 'broadcast'])
 
 
 # --- namedtuples for psutil.Process methods

psutil/_psbsd.py

@@ -50,6 +50,7 @@
 }
 
 PAGESIZE = os.sysconf("SC_PAGE_SIZE")
+AF_LINK = cext_posix.AF_LINK
 
 # extend base mem ntuple with BSD-specific memory metrics
 svmem = namedtuple(
@@ -211,6 +212,7 @@ def net_connections(kind):
 disk_usage = _psposix.disk_usage
 net_io_counters = cext.net_io_counters
 disk_io_counters = cext.disk_io_counters
+net_if_addrs = cext_posix.net_if_addrs
 
 
 def wrap_exceptions(fun):

psutil/_pslinux.py

@@ -54,6 +54,7 @@
 PAGESIZE = os.sysconf("SC_PAGE_SIZE")
 BOOT_TIME = None  # set later
 DEFAULT_ENCODING = sys.getdefaultencoding()
+AF_LINK = socket.AF_PACKET
 
 # ioprio_* constants http://linux.die.net/man/2/ioprio_get
 IOPRIO_CLASS_NONE = 0
@@ -555,6 +556,9 @@ def net_io_counters():
     return retdict
 
 
+net_if_addrs = cext_posix.net_if_addrs
+
+
 # --- disks
 
 def disk_io_counters():

psutil/_psosx.py

@@ -24,6 +24,7 @@
 # --- constants
 
 PAGESIZE = os.sysconf("SC_PAGE_SIZE")
+AF_LINK = cext_posix.AF_LINK
 
 # http://students.mimuw.edu.pl/lxr/source/include/net/tcp_states.h
 TCP_STATUSES = {
@@ -171,6 +172,7 @@ def net_connections(kind='inet'):
 disk_usage = _psposix.disk_usage
 net_io_counters = cext.net_io_counters
 disk_io_counters = cext.disk_io_counters
+net_if_addrs = cext_posix.net_if_addrs
 
 
 def wrap_exceptions(fun):

psutil/_pssunos.py

@@ -25,6 +25,7 @@
 __extra__all__ = ["CONN_IDLE", "CONN_BOUND"]
 
 PAGE_SIZE = os.sysconf('SC_PAGE_SIZE')
+AF_LINK = socket.AF_LINK
 
 CONN_IDLE = "IDLE"
 CONN_BOUND = "BOUND"
@@ -73,6 +74,7 @@
 disk_io_counters = cext.disk_io_counters
 net_io_counters = cext.net_io_counters
 disk_usage = _psposix.disk_usage
+net_if_addrs = cext_posix.net_if_addrs
 
 
 def virtual_memory():