API¶

Cyberpandas provides two extension types, IPArray and MACArray.

`IP Array`¶

class cyberpandas.IPArray(values)¶

Holder for IP Addresses.

IPArray is a container for IPv4 or IPv6 addresses. It satisfies pandas’ extension array interface, and so can be stored inside pandas.Series and pandas.DataFrame.

See Usage for more.

Constructors¶

The class constructor is flexible, and accepts integers, strings, or bytes. Dedicated alternate constructors are also available.

classmethod IPArray.from_pyints(values)¶

Construct an IPArray from a sequence of Python integers.

This can be useful for representing IPv6 addresses, which may be larger than 2**64.

Parameters

valuesSequence: Sequence of Python integers.

Examples

>>> IPArray.from_pyints([0, 10, 2 ** 64 + 1])
IPArray(['0.0.0.1', '0.0.0.2', '0.0.0.3', '0:0:0:1::'])

classmethod IPArray.from_bytes(bytestring)¶

Create an IPArray from a bytestring.

Parameters

bytestringbytes: Note that bytestring is a Python 3-style string of bytes, not a sequences of bytes where each element represents an IPAddress.

Returns

IPArray

See also

to_bytes
from_pyints

Examples

>>> arr = IPArray([10, 20])
>>> buf = arr.to_bytes()
>>> buf
b'\...x00'
>>> IPArray.from_bytes(buf)
IPArray(['0.0.0.10', '0.0.0.20'])

Finally, the top-level ip_range method can be used.

cyberpandas.ip_range(start=None, stop=None, step=None)¶

Generate a range of IP Addresses

Parameters

startint, str, IPv4Address, or IPv6Address, optional: Start of interval. The interval includes this value. The default start value is 0.
startint, str, IPv4Address, or IPv6Address, optional: End of interval. The interval does not include this value.
stepint, optional: Spacing between values. For any output out, this is the distance between two adjacent values, out[i+1] - out[i]. The default step size is 1. If step is specified as a position argument, start must also be given.

Returns

IPArray

Notes

Performance will worsen if either of start or stop are larger than 2**64.

Examples

From integers

>>> ip_range(1, 5)
IPArray(['0.0.0.1', '0.0.0.2', '0.0.0.3', '0.0.0.4'])

Or strings

>>> ip_range('0.0.0.1', '0.0.0.5')
IPArray(['0.0.0.1', '0.0.0.2', '0.0.0.3', '0.0.0.4'])

Or ipaddress objects

>>> ip_range(ipaddress.IPv4Address(1), ipaddress.IPv4Address(5))
IPArray(['0.0.0.1', '0.0.0.2', '0.0.0.3', '0.0.0.4'])

Serialization¶

Convert the IPArray to various formats.

IPArray.to_pyipaddress()¶

Convert the array to a list of scalar IP Adress objects.

Returns

addressesList: Each element of the list will be an ipaddress.IPv4Address or ipaddress.IPv6Address, depending on the size of that element.

See also

IPArray.to_pyints

Examples

>>> IPArray(['192.168.1.1', '2001:db8::1000']).to_pyipaddress()
[IPv4Address('192.168.1.1'), IPv6Address('2001:db8::1000')]

IPArray.to_pyints()¶

Convert the array to a list of Python integers.

Returns

addressesList[int]: These will be Python integers (not NumPy), which are unbounded in size.

See also

IPArray.to_pyipaddresses
IPArray.from_pyints

Examples

>>> IPArray(['192.168.1.1', '2001:db8::1000']).to_pyints()
[3232235777, 42540766411282592856903984951653830656]

IPArray.to_bytes()¶

Serialize the IPArray as a Python bytestring.

This and :meth:IPArray.from_bytes is the fastest way to roundtrip serialize and de-serialize an IPArray.

See also

IPArray.from_bytes

Examples

>>> arr = IPArray([10, 20])
>>> arr.to_bytes()
b'\...x00'

Methods¶

Various methods that are useful for pandas. When a Series contains an IPArray, calling the Series method will dispatch to these methods.

IPArray.take(indices, allow_fill=False, fill_value=None)¶

Take elements from an array.

Parameters

indicessequence of int

Indices to be taken.

allow_fillbool, default False

How to handle negative values in indices.

False: negative values in indices indicate positional indices from the right (the default). This is similar to numpy.take().
True: negative values in indices indicate missing values. These values are set to fill_value. Any other other negative values raise a ValueError.

fill_valueany, optional

Fill value to use for NA-indices when allow_fill is True. This may be None, in which case the default NA value for the type, self.dtype.na_value, is used.

For many ExtensionArrays, there will be two representations of fill_value: a user-facing “boxed” scalar, and a low-level physical NA value. fill_value should be the user-facing version, and the implementation should handle translating that to the physical version for processing the take if necessary.

Returns

ExtensionArray

Raises

IndexError: When the indices are out of bounds for the array.
ValueError: When indices contains negative values other than -1 and allow_fill is True.

See also

numpy.take
api.extensions.take

Notes

ExtensionArray.take is called by Series.__getitem__, .loc, iloc, when indices is a sequence of values. Additionally, it’s called by Series.reindex(), or any other method that causes realignment, with a fill_value.

Examples

Here’s an example implementation, which relies on casting the extension array to object dtype. This uses the helper method pandas.api.extensions.take().

def take(self, indices, allow_fill=False, fill_value=None):
    from pandas.core.algorithms import take

    # If the ExtensionArray is backed by an ndarray, then
    # just pass that here instead of coercing to object.
    data = self.astype(object)

    if allow_fill and fill_value is None:
        fill_value = self.dtype.na_value

    # fill value should always be translated from the scalar
    # type for the array, to the physical storage type for
    # the data, before passing to take.

    result = take(data, indices, fill_value=fill_value,
                  allow_fill=allow_fill)
    return self._from_sequence(result, dtype=self.dtype)

IPArray.unique()¶

Compute the ExtensionArray of unique values.

Returns

uniquesExtensionArray

IPArray.isin(other)¶

Check whether elements of self are in other.

Comparison is done elementwise.

Parameters

otherstr or sequences

For str other, the argument is attempted to be converted to an ipaddress.IPv4Network or a ipaddress.IPv6Network or an IPArray. If all those conversions fail, a TypeError is raised.

For a sequence of strings, the same conversion is attempted. You should not mix networks with addresses.

Finally, other may be an IPArray of addresses to compare to.

Returns

containedndarray: A 1-D boolean ndarray with the same length as self.

Examples

Comparison to a single network

>>> s = IPArray(['192.168.1.1', '255.255.255.255'])
>>> s.isin('192.168.1.0/24')
array([ True, False])

Comparison to many networks >>> s.isin([‘192.168.1.0/24’, ‘192.168.2.0/24’]) array([ True, False])

Comparison to many IP Addresses

>>> s.isin(['192.168.1.1', '192.168.1.2', '255.255.255.1']])
array([ True, False])

IPArray.isna()¶

Indicator for whether each element is missing.

The IPAddress 0 is used to indecate missing values.

Examples

>>> IPArray(['0.0.0.0', '192.168.1.1']).isna()
array([ True, False])

IP Address Attributes¶

IP addresss-specific attributes.

IPArray.is_ipv4¶: Indicator for whether each address fits in the IPv4 space.

IPArray.is_ipv6¶: Indicator for whether each address requires IPv6.

IPArray.version¶: IP version (4 or 6).

IPArray.is_multicast¶: Indiciator for whether each address is multicast.

IPArray.is_private¶: Indiciator for whether each address is private.

IPArray.is_global¶: Indiciator for whether each address is global.

IPArray.is_unspecified¶: Indiciator for whether each address is unspecified.

IPArray.is_reserved¶: Indiciator for whether each address is reserved.

IPArray.is_loopback¶: Indiciator for whether each address is loopback.

IPArray.is_link_local¶: Indiciator for whether each address is link local.

IPArray.netmask(v4_prefixlen=32, v6_prefixlen=128)¶

Compute an array of netmasks for an array of IP addresses.

Note that this is a method, rather than a property, to support taking v4_prefixlen and v6_prefixlen as arguments.

Parameters

v4_prefixlenint, default 32: Length of the network prefix, in bits, for IPv4 addresses
v6_prefixlenint, default 128: Lnegth of the network prefix, in bits, for IPv6 addresses

Returns

IPArray

See also

IPArray.hostmask

Examples

>>> arr = ip.IPArray(['192.0.0.0', '1:1::'])
>>> arr.netmask(v4_prefixlen=16, v6_prefixlen=32)
IPArray(['255.255.0.0', 'ffff:ffff::'])

IPArray.hostmask(v4_prefixlen=32, v6_prefixlen=128)¶

Compute an array of hostmasks for an array of IP addresses.

Parameters

v4_prefixlenint, default 32: Length of the network prefix, in bits, for IPv4 addresses
v6_prefixlenint, default 128: Lnegth of the network prefix, in bits, for IPv6 addresses

Returns

IPArray

See also

IPArray.netmask

Examples

>>> arr = ip.IPArray(['192.0.0.0', '1:1::'])
>>> arr.netmask(v4_prefixlen=16, v6_prefixlen=32)
IPArray(['0.0.255.255', '::ffff:ffff:ffff:ffff:ffff:ffff'])

IPArray.mask(mask)¶

Apply a host or subnet mask.

Parameters

maskIPArray: The host or subnet mask to be applied

Returns

maskedIPArray

See also

netmask
hostmask

Examples

>>> arr = IPArray(['216.003.128.12', '192.168.100.1'])
>>> mask = arr.netmask(v4_prefixlen=24)
>>> mask
IPArray(['255.255.255.0', '255.255.255.0'])
>>> arr.mask(mask)
IPArray(['216.3.128.0', '192.168.100.0'])

`MACArray`¶

utofun .. autoclass:: MACArray

API¶

IP Array¶

Constructors¶

Serialization¶

Methods¶

IP Address Attributes¶

MACArray¶

`IP Array`¶

`MACArray`¶