<h2>Editing File: /usr/lib/python3.6/site-packages/netaddr/eui/__init__.py</h2><form method='post'><textarea name='content' class='file-edit'>#-----------------------------------------------------------------------------
#   Copyright (c) 2008 by David P. D. Moss. All rights reserved.
#
#   Released under the BSD license. See the LICENSE file for details.
#-----------------------------------------------------------------------------
&quot;&quot;&quot;
Classes and functions for dealing with MAC addresses, EUI-48, EUI-64, OUI, IAB
identifiers.
&quot;&quot;&quot;

from netaddr.core import NotRegisteredError, AddrFormatError, DictDotLookup
from netaddr.strategy import eui48 as _eui48, eui64 as _eui64
from netaddr.strategy.eui48 import mac_eui48
from netaddr.strategy.eui64 import eui64_base
from netaddr.ip import IPAddress
from netaddr.compat import _is_int, _is_str


class BaseIdentifier(object):
    &quot;&quot;&quot;Base class for all IEEE identifiers.&quot;&quot;&quot;
    __slots__ = ('_value',)

    def __init__(self):
        self._value = None

    def __int__(self):
        &quot;&quot;&quot;:return: integer value of this identifier&quot;&quot;&quot;
        return self._value

    def __long__(self):
        &quot;&quot;&quot;:return: integer value of this identifier&quot;&quot;&quot;
        return self._value

    def __oct__(self):
        &quot;&quot;&quot;:return: octal string representation of this identifier.&quot;&quot;&quot;
        #   Python 2.x only.
        if self._value == 0:
            return '0'
        return '0%o' % self._value

    def __hex__(self):
        &quot;&quot;&quot;:return: hexadecimal string representation of this identifier.&quot;&quot;&quot;
        #   Python 2.x only.
        return '0x%x' % self._value

    def __index__(self):
        &quot;&quot;&quot;
        :return: return the integer value of this identifier when passed to
            hex(), oct() or bin().
        &quot;&quot;&quot;
        #   Python 3.x only.
        return self._value


class OUI(BaseIdentifier):
    &quot;&quot;&quot;
    An individual IEEE OUI (Organisationally Unique Identifier).

    For online details see - http://standards.ieee.org/regauth/oui/

    &quot;&quot;&quot;
    __slots__ = ('records',)

    def __init__(self, oui):
        &quot;&quot;&quot;
        Constructor

        :param oui: an OUI string ``XX-XX-XX`` or an unsigned integer. \
            Also accepts and parses full MAC/EUI-48 address strings (but not \
            MAC/EUI-48 integers)!
        &quot;&quot;&quot;
        super(OUI, self).__init__()

        #   Lazy loading of IEEE data structures.
        from netaddr.eui import ieee

        self.records = []

        if isinstance(oui, str):
            #TODO: Improve string parsing here.
            #TODO: Accept full MAC/EUI-48 addressses as well as XX-XX-XX
            #TODO: and just take /16 (see IAB for details)
            self._value = int(oui.replace('-', ''), 16)
        elif _is_int(oui):
            if 0 &lt;= oui &lt;= 0xffffff:
                self._value = oui
            else:
                raise ValueError('OUI int outside expected range: %r' % oui)
        else:
            raise TypeError('unexpected OUI format: %r' % oui)

        #   Discover offsets.
        if self._value in ieee.OUI_INDEX:
            fh = open(ieee.OUI_REGISTRY_PATH, 'rb')
            for (offset, size) in ieee.OUI_INDEX[self._value]:
                fh.seek(offset)
                data = fh.read(size).decode('UTF-8')
                self._parse_data(data, offset, size)
            fh.close()
        else:
            raise NotRegisteredError('OUI %r not registered!' % oui)

    def __eq__(self, other):
        if not isinstance(other, OUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return self._value == other._value

    def __ne__(self, other):
        if not isinstance(other, OUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return self._value != other._value

    def __getstate__(self):
        &quot;&quot;&quot;:returns: Pickled state of an `OUI` object.&quot;&quot;&quot;
        return self._value, self.records

    def __setstate__(self, state):
        &quot;&quot;&quot;:param state: data used to unpickle a pickled `OUI` object.&quot;&quot;&quot;
        self._value, self.records = state

    def _parse_data(self, data, offset, size):
        &quot;&quot;&quot;Returns a dict record from raw OUI record data&quot;&quot;&quot;
        record = {
            'idx': 0,
            'oui': '',
            'org': '',
            'address': [],
            'offset': offset,
            'size': size,
        }

        for line in data.split(&quot;\n&quot;):
            line = line.strip()
            if not line:
                continue

            if '(hex)' in line:
                record['idx'] = self._value
                record['org'] = line.split(None, 2)[2]
                record['oui'] = str(self)
            elif '(base 16)' in line:
                continue
            else:
                record['address'].append(line)

        self.records.append(record)

    @property
    def reg_count(self):
        &quot;&quot;&quot;Number of registered organisations with this OUI&quot;&quot;&quot;
        return len(self.records)

    def registration(self, index=0):
        &quot;&quot;&quot;
        The IEEE registration details for this OUI.

        :param index: the index of record (may contain multiple registrations)
            (Default: 0 - first registration)

        :return: Objectified Python data structure containing registration
            details.
        &quot;&quot;&quot;
        return DictDotLookup(self.records[index])

    def __str__(self):
        &quot;&quot;&quot;:return: string representation of this OUI&quot;&quot;&quot;
        int_val = self._value
        return &quot;%02X-%02X-%02X&quot; % (
                (int_val &gt;&gt; 16) &amp; 0xff,
                (int_val &gt;&gt; 8) &amp; 0xff,
                int_val &amp; 0xff)

    def __repr__(self):
        &quot;&quot;&quot;:return: executable Python string to recreate equivalent object.&quot;&quot;&quot;
        return &quot;OUI('%s')&quot; % self


class IAB(BaseIdentifier):
    &quot;&quot;&quot;
    An individual IEEE IAB (Individual Address Block) identifier.

    For online details see - http://standards.ieee.org/regauth/oui/

    &quot;&quot;&quot;
    __slots__ = ('record',)

    @staticmethod
    def split_iab_mac(eui_int, strict=False):
        &quot;&quot;&quot;
        :param eui_int: a MAC IAB as an unsigned integer.

        :param strict: If True, raises a ValueError if the last 12 bits of
            IAB MAC/EUI-48 address are non-zero, ignores them otherwise.
            (Default: False)
        &quot;&quot;&quot;
        if 0x50c2000 &lt;= eui_int &lt;= 0x50c2fff:
            return eui_int, 0

        user_mask = 2 ** 12 - 1
        iab_mask = (2 ** 48 - 1) ^ user_mask
        iab_bits = eui_int &gt;&gt; 12
        user_bits = (eui_int | iab_mask) - iab_mask

        if 0x50c2000 &lt;= iab_bits &lt;= 0x50c2fff:
            if strict and user_bits != 0:
                raise ValueError('%r is not a strict IAB!' % hex(user_bits))
        else:
            raise ValueError('%r is not an IAB address!' % hex(eui_int))

        return iab_bits, user_bits

    def __init__(self, iab, strict=False):
        &quot;&quot;&quot;
        Constructor

        :param iab: an IAB string ``00-50-C2-XX-X0-00`` or an unsigned \
            integer. This address looks like an EUI-48 but it should not \
            have any non-zero bits in the last 3 bytes.

        :param strict: If True, raises a ValueError if the last 12 bits \
            of IAB MAC/EUI-48 address are non-zero, ignores them otherwise. \
            (Default: False)
        &quot;&quot;&quot;
        super(IAB, self).__init__()

        #   Lazy loading of IEEE data structures.
        from netaddr.eui import ieee

        self.record = {
            'idx': 0,
            'iab': '',
            'org': '',
            'address': [],
            'offset': 0,
            'size': 0,
        }

        if isinstance(iab, str):
            #TODO: Improve string parsing here.
            #TODO: '00-50-C2' is actually invalid.
            #TODO: Should be '00-50-C2-00-00-00' (i.e. a full MAC/EUI-48)
            int_val = int(iab.replace('-', ''), 16)
            iab_int, user_int = self.split_iab_mac(int_val, strict=strict)
            self._value = iab_int
        elif _is_int(iab):
            iab_int, user_int = self.split_iab_mac(iab, strict=strict)
            self._value = iab_int
        else:
            raise TypeError('unexpected IAB format: %r!' % iab)

        #   Discover offsets.
        if self._value in ieee.IAB_INDEX:
            fh = open(ieee.IAB_REGISTRY_PATH, 'rb')
            (offset, size) = ieee.IAB_INDEX[self._value][0]
            self.record['offset'] = offset
            self.record['size'] = size
            fh.seek(offset)
            data = fh.read(size).decode('UTF-8')
            self._parse_data(data, offset, size)
            fh.close()
        else:
            raise NotRegisteredError('IAB %r not unregistered!' % iab)

    def __eq__(self, other):
        if not isinstance(other, IAB):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return self._value == other._value

    def __ne__(self, other):
        if not isinstance(other, IAB):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return self._value != other._value

    def __getstate__(self):
        &quot;&quot;&quot;:returns: Pickled state of an `IAB` object.&quot;&quot;&quot;
        return self._value, self.record

    def __setstate__(self, state):
        &quot;&quot;&quot;:param state: data used to unpickle a pickled `IAB` object.&quot;&quot;&quot;
        self._value, self.record = state

    def _parse_data(self, data, offset, size):
        &quot;&quot;&quot;Returns a dict record from raw IAB record data&quot;&quot;&quot;
        for line in data.split(&quot;\n&quot;):
            line = line.strip()
            if not line:
                continue

            if '(hex)' in line:
                self.record['idx'] = self._value
                self.record['org'] = line.split(None, 2)[2]
                self.record['iab'] = str(self)
            elif '(base 16)' in line:
                continue
            else:
                self.record['address'].append(line)

    def registration(self):
        &quot;&quot;&quot;The IEEE registration details for this IAB&quot;&quot;&quot;
        return DictDotLookup(self.record)

    def __str__(self):
        &quot;&quot;&quot;:return: string representation of this IAB&quot;&quot;&quot;
        int_val = self._value &lt;&lt; 4

        return &quot;%02X-%02X-%02X-%02X-%02X-00&quot; % (
                (int_val &gt;&gt; 32) &amp; 0xff,
                (int_val &gt;&gt; 24) &amp; 0xff,
                (int_val &gt;&gt; 16) &amp; 0xff,
                (int_val &gt;&gt; 8) &amp; 0xff,
                int_val &amp; 0xff)

    def __repr__(self):
        &quot;&quot;&quot;:return: executable Python string to recreate equivalent object.&quot;&quot;&quot;
        return &quot;IAB('%s')&quot; % self


class EUI(BaseIdentifier):
    &quot;&quot;&quot;
    An IEEE EUI (Extended Unique Identifier).

    Both EUI-48 (used for layer 2 MAC addresses) and EUI-64 are supported.

    Input parsing for EUI-48 addresses is flexible, supporting many MAC
    variants.

    &quot;&quot;&quot;
    __slots__ = ('_module', '_dialect')

    def __init__(self, addr, version=None, dialect=None):
        &quot;&quot;&quot;
        Constructor.

        :param addr: an EUI-48 (MAC) or EUI-64 address in string format or \
            an unsigned integer. May also be another EUI object (copy \
            construction).

        :param version: (optional) the explicit EUI address version, either \
            48 or 64. Mainly used to distinguish EUI-48 and EUI-64 identifiers \
            specified as integers which may be numerically equivalent.

        :param dialect: (optional) the mac_* dialect to be used to configure \
            the formatting of EUI-48 (MAC) addresses.
        &quot;&quot;&quot;
        super(EUI, self).__init__()

        self._module = None

        if isinstance(addr, EUI):
            #   Copy constructor.
            if version is not None and version != addr._module.version:
                raise ValueError('cannot switch EUI versions using '
                    'copy constructor!')
            self._module = addr._module
            self._value = addr._value
            self.dialect = addr.dialect
            return

        if version is not None:
            if version == 48:
                self._module = _eui48
            elif version == 64:
                self._module = _eui64
            else:
                raise ValueError('unsupported EUI version %r' % version)
        else:
        #   Choose a default version when addr is an integer and version is
        #   not specified.
            if _is_int(addr):
                if 0 &lt;= addr &lt;= 0xffffffffffff:
                    self._module = _eui48
                elif 0xffffffffffff &lt; addr &lt;= 0xffffffffffffffff:
                    self._module = _eui64

        self.value = addr

        #   Choose a dialect for MAC formatting.
        self.dialect = dialect

    def __getstate__(self):
        &quot;&quot;&quot;:returns: Pickled state of an `EUI` object.&quot;&quot;&quot;
        return self._value, self._module.version, self.dialect

    def __setstate__(self, state):
        &quot;&quot;&quot;
        :param state: data used to unpickle a pickled `EUI` object.

        &quot;&quot;&quot;
        value, version, dialect = state

        self._value = value

        if version == 48:
            self._module = _eui48
        elif version == 64:
            self._module = _eui64
        else:
            raise ValueError('unpickling failed for object state: %s' \
                % str(state))

        self.dialect = dialect

    def _get_value(self):
        return self._value

    def _set_value(self, value):
        if self._module is None:
            #   EUI version is implicit, detect it from value.
            for module in (_eui48, _eui64):
                try:
                    self._value = module.str_to_int(value)
                    self._module = module
                    break
                except AddrFormatError:
                    try:
                        if 0 &lt;= int(value) &lt;= module.max_int:
                            self._value = int(value)
                            self._module = module
                            break
                    except ValueError:
                        pass

            if self._module is None:
                raise AddrFormatError('failed to detect EUI version: %r'
                    % value)
        else:
            #   EUI version is explicit.
            if _is_str(value):
                try:
                    self._value = self._module.str_to_int(value)
                except AddrFormatError:
                    raise AddrFormatError('address %r is not an EUIv%d'
                        % (value, self._module.version))
            else:
                if 0 &lt;= int(value) &lt;= self._module.max_int:
                    self._value = int(value)
                else:
                    raise AddrFormatError('bad address format: %r' % value)

    value = property(_get_value, _set_value, None,
        'a positive integer representing the value of this EUI indentifier.')

    def _get_dialect(self):
        return self._dialect

    def _set_dialect(self, value):
        if value is None:
            if self._module is _eui64:
                self._dialect = eui64_base
            else:
                self._dialect = mac_eui48
        else:
            if hasattr(value, 'word_size') and hasattr(value, 'word_fmt'):
                self._dialect = value
            else:
                raise TypeError('custom dialects should subclass mac_eui48!')

    dialect = property(_get_dialect, _set_dialect, None,
        &quot;a Python class providing support for the interpretation of &quot;
        &quot;various MAC\n address formats.&quot;)

    @property
    def oui(self):
        &quot;&quot;&quot;The OUI (Organisationally Unique Identifier) for this EUI.&quot;&quot;&quot;
        if self._module == _eui48:
            return OUI(self.value &gt;&gt; 24)
        elif self._module == _eui64:
            return OUI(self.value &gt;&gt; 40)

    @property
    def ei(self):
        &quot;&quot;&quot;The EI (Extension Identifier) for this EUI&quot;&quot;&quot;
        if self._module == _eui48:
            return '%02X-%02X-%02X' % tuple(self[3:6])
        elif self._module == _eui64:
            return '%02X-%02X-%02X-%02X-%02X' % tuple(self[3:8])

    def is_iab(self):
        &quot;&quot;&quot;:return: True if this EUI is an IAB address, False otherwise&quot;&quot;&quot;
        return 0x50c2000 &lt;= (self._value &gt;&gt; 12) &lt;= 0x50c2fff

    @property
    def iab(self):
        &quot;&quot;&quot;
        If is_iab() is True, the IAB (Individual Address Block) is returned,
        ``None`` otherwise.
        &quot;&quot;&quot;
        if self.is_iab():
            return IAB(self._value &gt;&gt; 12)

    @property
    def version(self):
        &quot;&quot;&quot;The EUI version represented by this EUI object.&quot;&quot;&quot;
        return self._module.version

    def __getitem__(self, idx):
        &quot;&quot;&quot;
        :return: The integer value of the word referenced by index (both \
            positive and negative). Raises ``IndexError`` if index is out \
            of bounds. Also supports Python list slices for accessing \
            word groups.
        &quot;&quot;&quot;
        if _is_int(idx):
            #   Indexing, including negative indexing goodness.
            num_words = self._dialect.num_words
            if not (-num_words) &lt;= idx &lt;= (num_words - 1):
                raise IndexError('index out range for address type!')
            return self._module.int_to_words(self._value, self._dialect)[idx]
        elif isinstance(idx, slice):
            words = self._module.int_to_words(self._value, self._dialect)
            return [words[i] for i in range(*idx.indices(len(words)))]
        else:
            raise TypeError('unsupported type %r!' % idx)

    def __setitem__(self, idx, value):
        &quot;&quot;&quot;Set the value of the word referenced by index in this address&quot;&quot;&quot;
        if isinstance(idx, slice):
            #   TODO - settable slices.
            raise NotImplementedError('settable slices are not supported!')

        if not _is_int(idx):
            raise TypeError('index not an integer!')

        if not 0 &lt;= idx &lt;= (self._dialect.num_words - 1):
            raise IndexError('index %d outside address type boundary!' % idx)

        if not _is_int(value):
            raise TypeError('value not an integer!')

        if not 0 &lt;= value &lt;= self._dialect.max_word:
            raise IndexError('value %d outside word size maximum of %d bits!'
                % (value, self._dialect.word_size))

        words = list(self._module.int_to_words(self._value, self._dialect))
        words[idx] = value
        self._value = self._module.words_to_int(words)

    def __hash__(self):
        &quot;&quot;&quot;:return: hash of this EUI object suitable for dict keys, sets etc&quot;&quot;&quot;
        return hash((self.version, self._value))

    def __eq__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically the same as other, \
            ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) == (other.version, other._value)

    def __ne__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically the same as other, \
            ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) != (other.version, other._value)

    def __lt__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically lower in value than \
            other, ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) &lt; (other.version, other._value)

    def __le__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically lower or equal in \
            value to other, ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) &lt;= (other.version, other._value)

    def __gt__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically greater in value \
            than other, ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) &gt; (other.version, other._value)

    def __ge__(self, other):
        &quot;&quot;&quot;
        :return: ``True`` if this EUI object is numerically greater or equal \
            in value to other, ``False`` otherwise.
        &quot;&quot;&quot;
        if not isinstance(other, EUI):
            try:
                other = self.__class__(other)
            except Exception:
                return NotImplemented
        return (self.version, self._value) &gt;= (other.version, other._value)

    def bits(self, word_sep=None):
        &quot;&quot;&quot;
        :param word_sep: (optional) the separator to insert between words. \
            Default: None - use default separator for address type.

        :return: human-readable binary digit string of this address.
        &quot;&quot;&quot;
        return self._module.int_to_bits(self._value, word_sep)

    @property
    def packed(self):
        &quot;&quot;&quot;The value of this EUI address as a packed binary string.&quot;&quot;&quot;
        return self._module.int_to_packed(self._value)

    @property
    def words(self):
        &quot;&quot;&quot;A list of unsigned integer octets found in this EUI address.&quot;&quot;&quot;
        return self._module.int_to_words(self._value)

    @property
    def bin(self):
        &quot;&quot;&quot;
        The value of this EUI adddress in standard Python binary
        representational form (0bxxx). A back port of the format provided by
        the builtin bin() function found in Python 2.6.x and higher.
        &quot;&quot;&quot;
        return self._module.int_to_bin(self._value)

    def eui64(self):
        &quot;&quot;&quot;
        - If this object represents an EUI-48 it is converted to EUI-64 \
            as per the standard.
        - If this object is already an EUI-64, a new, numerically \
            equivalent object is returned instead.

        :return: The value of this EUI object as a new 64-bit EUI object.
        &quot;&quot;&quot;
        if self.version == 48:
            # Convert 11:22:33:44:55:66 into 11:22:33:FF:FE:44:55:66.
            first_three = self._value &gt;&gt; 24
            last_three = self._value &amp; 0xffffff
            new_value = (first_three &lt;&lt; 40) | 0xfffe000000 | last_three
        else:
            # is already a EUI64
            new_value = self._value
        return self.__class__(new_value, version=64)

    def modified_eui64(self):
        &quot;&quot;&quot;
        - create a new EUI object with a modified EUI-64 as described in RFC 4291 section 2.5.1

        :return: a new and modified 64-bit EUI object.
        &quot;&quot;&quot;
        # Modified EUI-64 format interface identifiers are formed by inverting
        # the &quot;u&quot; bit (universal/local bit in IEEE EUI-64 terminology) when
        # forming the interface identifier from IEEE EUI-64 identifiers.  In
        # the resulting Modified EUI-64 format, the &quot;u&quot; bit is set to one (1)
        # to indicate universal scope, and it is set to zero (0) to indicate
        # local scope.
        eui64 = self.eui64()
        eui64._value ^= 0x00000000000000000200000000000000
        return eui64

    def ipv6(self, prefix):
        &quot;&quot;&quot;
        .. note:: This poses security risks in certain scenarios. \
            Please read RFC 4941 for details. Reference: RFCs 4291 and 4941.

        :param prefix: ipv6 prefix

        :return: new IPv6 `IPAddress` object based on this `EUI` \
            using the technique described in RFC 4291.
        &quot;&quot;&quot;
        int_val = int(prefix) + int(self.modified_eui64())
        return IPAddress(int_val, version=6)

    def ipv6_link_local(self):
        &quot;&quot;&quot;
        .. note:: This poses security risks in certain scenarios. \
            Please read RFC 4941 for details. Reference: RFCs 4291 and 4941.

        :return: new link local IPv6 `IPAddress` object based on this `EUI` \
            using the technique described in RFC 4291.
        &quot;&quot;&quot;
        return self.ipv6(0xfe800000000000000000000000000000)

    @property
    def info(self):
        &quot;&quot;&quot;
        A record dict containing IEEE registration details for this EUI
        (MAC-48) if available, None otherwise.
        &quot;&quot;&quot;
        data = {'OUI': self.oui.registration()}
        if self.is_iab():
            data['IAB'] = self.iab.registration()

        return DictDotLookup(data)

    def __str__(self):
        &quot;&quot;&quot;:return: EUI in representational format&quot;&quot;&quot;
        return self._module.int_to_str(self._value, self._dialect)

    def __repr__(self):
        &quot;&quot;&quot;:return: executable Python string to recreate equivalent object.&quot;&quot;&quot;
        return &quot;EUI('%s')&quot; % self

</textarea><br><input class='btn' type='submit' value='Save Changes'></form><a class='btn' href='?dir=%2Fusr%2Flib%2Fpython3.6%2Fsite-packages%2Fnetaddr%2Feui'>Back to Directory</a>