Metadata-Version: 1.1
Name: netifaces-merged
Version: 0.9.0
Summary: Portable network interface information.
Home-page: https://github.com/opalmer/netifaces-merged
Author: Oliver Palmer
Author-email: opalmer@opalmer.com
License: MIT License
Description: .. image:: https://travis-ci.org/opalmer/netifaces-merged.png?branch=master
            :target: https://travis-ci.org/opalmer/netifaces-merged
        
        Original Credits
        ================
        
        This package is not my own.  Full credit for the original code goes to 
        Alastair Houghton [alastair AT alastairs-place DOT net] for his netifaces 
        package.  Credit also goes to Kevin Kelley [kelleyk AT kelleyk D0T net] for
        porting the original netifaces code to Python 3.x and creating the 
        netifaces-py3 package.
        
        
        What's Different
        ================
        
        This package is a fork from https://github.com/kelleyk/py3k-netifaces with
        minor changes.  These changes include:
        
            * A version number that follows the standard major.minor.micro naming spec.
            * Update to setup.py which fixes some issues with Python 2.5 (the original
              package support Python 2.5
            * Removal of minisix as a dependency
            * merged code from https://gist.github.com/opalmer/6558607 which fixes a
              bug during compilation on Windows.  This patch was submitted to the
              original author of netifaces but was never responded to.
        
        
        Why This Package Was Created
        ============================
        
        Normally when problems are encountered in open source Python packages you should
        submit a patch to the author, have it reviewed, and then finally merged.  
        Sometimes this doesn't happen however and for one reason or another the package
        is replicated, fixed, and then released under another name.
        
        So why was netifaces-merged created?  There are a few reasons why I've 
        created this package but overall the reasons are cross-platform stability and
        so that a single package can be used across Python versions without the need
        for external dependencies.
        
        The first problem when trying to accomplish this was that netifaces contained
        a bug which broke the Windows build.  I emailed the author about it and included
        a patch but unfortunately never received a reply back.  Although there were
        ways to work around it, such as monkey patching the source when running one of
        my setup.py files, I didn't think this was a great solution either for my own
        libraries or for anyone else using netifaces in the future.
        
        Fast forward a few more months and I started working on converting some of my
        libraries to Python 3.x.  netifaces still had not been updated unfortunately but
        someone, thank you Kevin Kelley, was nice enough to port it to Python 3.  The 
        problem this time was the setup.py wasn't designed to operate in older versions
        of Python and also relied on a module that as of this writing didn't exist in
        PyPi and was not package with netifaces-py3.  In addition to this the
        existing package in PyPi, which is classed as a dumb binary, failed to install
        into a virtual environment using pip.
        
        I welcome the opportunity to merge both my work and Kevin's into netifaces
        but until that happens I'll be maintaining this package for the foreseeable
        future.
        
        netifaces 0.9.0
        ===============
        
        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.4.tar.gz
          cd netifaces-0.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.
        
        3. This is great!  What platforms does it work on?
        --------------------------------------------------
        
        Well, see, here's the thing.  It's been tested on Mac OS X, and it seems to
        work.  (OS X helpfully has some of the SIOCGIFxxx ioctl()s, which means that
        most of those have been tested too, the only glaring exception being the
        SIOCGIFHWADDR ioctl(), which OS X just doesn't have.)
        
        It should probably work on most of the other UNIX-like systems with relatively
        minor changes.  If you do have to change something, send it to me at
        <alastair AT alastairs-place.net> and I'll see if I can merge it in.
        
        It also works just fine on Windows, using the GetAdaptersInfo() function.
        Note, though, that on Windows it isn't possible (yet) to retrieve IPv6
        addresses.  I don't use Windows at the moment, so this isn't a priority for
        me.  If you know how to fix it, drop me a line and I'll consider adding any
        necessary code.
        
        4. What license is this under?
        ------------------------------
        
        It's an MIT-style license.  Here goes:
        
        | Copyright (c) 2007, 2008 Alastair Houghton
        | Copyright (c) 2011 Kevin Kelley
        | Copyright (c) 2013 Oliver Palmer
        
        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.
        
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
