Metadata-Version: 1.1
Name: netifaces
Version: 0.10.4
Summary: Portable network interface information.
Home-page: https://bitbucket.org/al45tair/netifaces
Author: Alastair Houghton
Author-email: alastair@alastairs-place.net
License: MIT License
Description: netifaces 0.10.4
        ================
        
        .. image:: https://drone.io/bitbucket.org/al45tair/netifaces/status.png
           :target: https://drone.io/bitbucket.org/al45tair/netifaces/latest
           :alt: Build Status
        
        1. What is this?
        ----------------
        
        It's been annoying me for some time that there's no easy way to get the
        address(es) of the machine's network interfaces from Python.  There is
        a good reason for this difficulty, which is that it is virtually impossible
        to do so in a portable manner.  However, it seems to me that there should
        be a package you can easy_install that will take care of working out the
        details of doing so on the machine you're using, then you can get on with
        writing Python code without concerning yourself with the nitty gritty of
        system-dependent low-level networking APIs.
        
        This package attempts to solve that problem.
        
        2. How do I use it?
        -------------------
        
        First you need to install it, which you can do by typing::
        
          tar xvzf netifaces-0.10.4.tar.gz
          cd netifaces-0.10.4
          python setup.py install
        
        Once that's done, you'll need to start Python and do something like the
        following::
        
        >>> import netifaces
        
        Then if you enter
        
        >>> netifaces.interfaces()
        ['lo0', 'gif0', 'stf0', 'en0', 'en1', 'fw0']
        
        you'll see the list of interface identifiers for your machine.
        
        You can ask for the addresses of a particular interface by doing
        
        >>> netifaces.ifaddresses('lo0')
        {18: [{'addr': ''}], 2: [{'peer': '127.0.0.1', 'netmask': '255.0.0.0', 'addr': '127.0.0.1'}], 30: [{'peer': '::1', 'netmask': 'ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff', 'addr': '::1'}, {'peer': '', 'netmask': 'ffff:ffff:ffff:ffff::', 'addr': 'fe80::1%lo0'}]}
        
        Hmmmm.  That result looks a bit cryptic; let's break it apart and explain
        what each piece means.  It returned a dictionary, so let's look there first::
        
          { 18: [...], 2: [...], 30: [...] }
        
        Each of the numbers refers to a particular address family.  In this case, we
        have three address families listed; on my system, 18 is ``AF_LINK`` (which means
        the link layer interface, e.g. Ethernet), 2 is ``AF_INET`` (normal Internet
        addresses), and 30 is ``AF_INET6`` (IPv6).
        
        But wait!  Don't use these numbers in your code.  The numeric values here are
        system dependent; fortunately, I thought of that when writing netifaces, so
        the module declares a range of values that you might need.  e.g.
        
        >>> netifaces.AF_LINK
        18
        
        Again, on your system, the number may be different.
        
        So, what we've established is that the dictionary that's returned has one
        entry for each address family for which this interface has an address.  Let's
        take a look at the ``AF_INET`` addresses now:
        
        >>> addrs = netifaces.ifaddresses('lo0')
        >>> addrs[netifaces.AF_INET]
        [{'peer': '127.0.0.1', 'netmask': '255.0.0.0', 'addr': '127.0.0.1'}]
        
        You might be wondering why this value is a list.  The reason is that it's
        possible for an interface to have more than one address, even within the
        same family.  I'll say that again: *you can have more than one address of
        the same type associated with each interface*.
        
        *Asking for "the" address of a particular interface doesn't make sense.*
        
        Right, so, we can see that this particular interface only has one address,
        and, because it's a loopback interface, it's point-to-point and therefore
        has a *peer* address rather than a broadcast address.
        
        Let's look at a more interesting interface.
        
        >>> addrs = netifaces.ifaddresses('en0')
        >>> addrs[netifaces.AF_INET]
        [{'broadcast': '10.15.255.255', 'netmask': '255.240.0.0', 'addr': '10.0.1.4'}, {'broadcast': '192.168.0.255', 'addr': '192.168.0.47'}]
        
        This interface has two addresses (see, I told you...)  Both of them are
        regular IPv4 addresses, although in one case the netmask has been changed
        from its default.  The netmask *may not* appear on your system if it's set
        to the default for the address range.
        
        Because this interface isn't point-to-point, it also has broadcast addresses.
        
        Now, say we want, instead of the IP addresses, to get the MAC address; that
        is, the hardware address of the Ethernet adapter running this interface.  We
        can do
        
        >>> addrs[netifaces.AF_LINK]
        [{'addr': '00:12:34:56:78:9a'}]
        
        Note that this may not be available on platforms without getifaddrs(), unless
        they happen to implement ``SIOCGIFHWADDR``.  Note also that you just get the
        address; it's unlikely that you'll see anything else with an ``AF_LINK`` address.
        Oh, and don't assume that all ``AF_LINK`` addresses are Ethernet; you might, for
        instance, be on a Mac, in which case:
        
        >>> addrs = netifaces.ifaddresses('fw0')
        >>> addrs[netifaces.AF_LINK]
        [{'addr': '00:12:34:56:78:9a:bc:de'}]
        
        No, that isn't an exceptionally long Ethernet MAC address---it's a FireWire
        address.
        
        As of version 0.10.0, you can also obtain a list of gateways on your
        machine:
        
        >>> netifaces.gateways()
        {2: [('10.0.1.1', 'en0', True), ('10.2.1.1', 'en1', False)], 30: [('fe80::1', 'en0', True)], 'default': { 2: ('10.0.1.1', 'en0'), 30: ('fe80::1', 'en0') }}
        
        This dictionary is keyed on address family---in this case, ``AF_INET``---and
        each entry is a list of gateways as ``(address, interface, is_default)`` tuples.
        Notice that here we have two separate gateways for IPv4 (``AF_INET``); some
        operating systems support configurations like this and can either route packets
        based on their source, or based on administratively configured routing tables.
        
        For convenience, we also allow you to index the dictionary with the special
        value ``'default'``, which returns a dictionary mapping address families to the
        default gateway in each case.  Thus you can get the default IPv4 gateway with
        
        >>> gws = netifaces.gateways()
        >>> gws['default'][netifaces.AF_INET]
        ('10.0.1.1', 'en0')
        
        Do note that there may be no default gateway for any given address family;
        this is currently very common for IPv6 and much less common for IPv4 but it
        can happen even for ``AF_INET``.
        
        BTW, if you're trying to configure your machine to have multiple gateways for
        the same address family, it's a very good idea to check the documentation for
        your operating system *very* carefully, as some systems become extremely
        confused or route packets in a non-obvious manner.
        
        I'm very interested in hearing from anyone (on any platform) for whom the
        ``gateways()`` method doesn't produce the expected results.  It's quite
        complicated extracting this information from the operating system (whichever
        operating system we're talking about), and so I expect there's at least one
        system out there where this just won't work.
        
        3. This is great!  What platforms does it work on?
        --------------------------------------------------
        
        It gets regular testing on OS X, Linux and Windows.  It has also been used
        successfully on Solaris, and it's expected to work properly on other UNIX-like
        systems as well.  If you are running something that is not supported, and
        wish to contribute a patch, please use BitBucket to send a pull request.
        
        4. What license is this under?
        ------------------------------
        
        It's an MIT-style license.  Here goes:
        
        Copyright (c) 2007-2014 Alastair Houghton
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        5. Why the jump to 0.10.0?
        --------------------------
        
        Because someone released a fork of netifaces with the version 0.9.0.
        Hopefully skipping the version number should remove any confusion.  In 
        addition starting with 0.10.0 Python 3 is now supported and other 
        features/bugfixes have been included as well.  See the CHANGELOG for a
        more complete list of changes.
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: System :: Networking
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.5
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3