Add stubs for netaddr (#9431)

Co-authored-by: Alex Waygood <[email protected]>

stubs/netaddr/@tests/stubtest_allowlist.txt

@@ -0,0 +1,16 @@
+# Error: is not present in stub
+# =============================
+netaddr.core.a  # This is a temporary module attribute used to detect python version
+
+# These are unnecessary re-exports
+netaddr.ip.INET_PTON
+netaddr.ip.N
+netaddr.ip.NOHOST
+netaddr.ip.P
+netaddr.ip.Z
+netaddr.ip.ZEROFILL
+
+
+# Error: is not present at runtime
+# ================================
+netaddr.ip.iana.XMLRecordParser.__getattr__  # __init__ has `self.__dict__.update(kwargs)`

stubs/netaddr/METADATA.toml

@@ -0,0 +1,4 @@
+version = "0.8.*"
+
+[tool.stubtest]
+ignore_missing_stub = false

stubs/netaddr/netaddr/__init__.pyi

@@ -0,0 +1,75 @@
+from netaddr.contrib.subnet_splitter import SubnetSplitter as SubnetSplitter
+from netaddr.core import (
+    INET_PTON as INET_PTON,
+    NOHOST as NOHOST,
+    ZEROFILL as ZEROFILL,
+    AddrConversionError as AddrConversionError,
+    AddrFormatError as AddrFormatError,
+    N as N,
+    NotRegisteredError as NotRegisteredError,
+    P as P,
+    Z as Z,
+)
+from netaddr.eui import EUI as EUI, IAB as IAB, OUI as OUI
+from netaddr.ip import (
+    IPAddress as IPAddress,
+    IPNetwork as IPNetwork,
+    IPRange as IPRange,
+    all_matching_cidrs as all_matching_cidrs,
+    cidr_abbrev_to_verbose as cidr_abbrev_to_verbose,
+    cidr_exclude as cidr_exclude,
+    cidr_merge as cidr_merge,
+    iprange_to_cidrs as iprange_to_cidrs,
+    iter_iprange as iter_iprange,
+    iter_unique_ips as iter_unique_ips,
+    largest_matching_cidr as largest_matching_cidr,
+    smallest_matching_cidr as smallest_matching_cidr,
+    spanning_cidr as spanning_cidr,
+)
+from netaddr.ip.glob import (
+    IPGlob as IPGlob,
+    cidr_to_glob as cidr_to_glob,
+    glob_to_cidrs as glob_to_cidrs,
+    glob_to_iprange as glob_to_iprange,
+    glob_to_iptuple as glob_to_iptuple,
+    iprange_to_globs as iprange_to_globs,
+    valid_glob as valid_glob,
+)
+from netaddr.ip.nmap import iter_nmap_range as iter_nmap_range, valid_nmap_range as valid_nmap_range
+from netaddr.ip.rfc1924 import base85_to_ipv6 as base85_to_ipv6, ipv6_to_base85 as ipv6_to_base85
+from netaddr.ip.sets import IPSet as IPSet
+from netaddr.strategy.eui48 import (
+    mac_bare as mac_bare,
+    mac_cisco as mac_cisco,
+    mac_eui48 as mac_eui48,
+    mac_pgsql as mac_pgsql,
+    mac_unix as mac_unix,
+    mac_unix_expanded as mac_unix_expanded,
+    valid_str as __eui48_valid_str,
+)
+from netaddr.strategy.eui64 import (
+    eui64_bare as eui64_bare,
+    eui64_base as eui64_base,
+    eui64_cisco as eui64_cisco,
+    eui64_unix as eui64_unix,
+    eui64_unix_expanded as eui64_unix_expanded,
+    valid_str as __eui64_valid_str,
+)
+from netaddr.strategy.ipv4 import valid_str as __ipv4_valid_str
+from netaddr.strategy.ipv6 import (
+    ipv6_compact as ipv6_compact,
+    ipv6_full as ipv6_full,
+    ipv6_verbose as ipv6_verbose,
+    valid_str as __ipv6_valid_str,
+)
+
+# These are reexported with different names
+valid_ipv4 = __ipv4_valid_str
+valid_ipv6 = __ipv6_valid_str
+valid_mac = __eui48_valid_str
+valid_eui64 = __eui64_valid_str
+
+# Module constants
+__version__: str
+VERSION: tuple[int, ...]
+STATUS: str

stubs/netaddr/netaddr/cli.pyi

@@ -0,0 +1,3 @@
+from netaddr import *
+
+def main() -> None: ...

stubs/netaddr/netaddr/compat.pyi

@@ -0,0 +1,2 @@
+# Python 2 compatibility module
+# All members are prefixed with "_", nothing to declare.

stubs/netaddr/netaddr/contrib/subnet_splitter.pyi

@@ -0,0 +1,7 @@
+from netaddr.ip import IPNetwork, _IPAddressAddr
+
+class SubnetSplitter:
+    def __init__(self, base_cidr: _IPAddressAddr) -> None: ...
+    def extract_subnet(self, prefix: int, count: int | None = ...) -> list[IPNetwork]: ...
+    def available_subnets(self) -> list[IPNetwork]: ...
+    def remove_subnet(self, ip_network: IPNetwork) -> None: ...

stubs/netaddr/netaddr/core.pyi

@@ -0,0 +1,38 @@
+from _typeshed import Incomplete, SupportsWrite
+from collections.abc import Iterator, Mapping
+from typing_extensions import Final
+
+BIG_ENDIAN_PLATFORM: bool
+P: Final = 1
+INET_PTON: Final = 1
+Z: Final = 2
+ZEROFILL: Final = 2
+N: Final = 4
+NOHOST: Final = 4
+
+class AddrFormatError(Exception): ...
+class AddrConversionError(Exception): ...
+class NotRegisteredError(Exception): ...
+
+def num_bits(int_val: int) -> int: ...
+
+class Subscriber:
+    def update(self, data: Incomplete) -> None: ...
+
+class PrettyPrinter(Subscriber):
+    fh: SupportsWrite[str]
+    write_eol: bool
+    def __init__(self, fh: SupportsWrite[str] = ..., write_eol: bool = ...) -> None: ...
+    def update(self, data: object) -> None: ...
+
+class Publisher:
+    subscribers: list[Subscriber]
+    def __init__(self) -> None: ...
+    def attach(self, subscriber: Subscriber) -> None: ...
+    def detach(self, subscriber: Subscriber) -> None: ...
+    def notify(self, data: object) -> None: ...
+
+class DictDotLookup:
+    def __init__(self, d: Mapping[str, object]) -> None: ...
+    def __getitem__(self, name: str) -> object: ...
+    def __iter__(self) -> Iterator[str]: ...

stubs/netaddr/netaddr/eui/__init__.pyi

@@ -0,0 +1,85 @@
+from _typeshed import Self
+from typing import ClassVar, SupportsInt, overload
+from typing_extensions import Literal, SupportsIndex
+
+from netaddr.core import DictDotLookup
+from netaddr.ip import IPAddress
+from netaddr.strategy.eui48 import mac_eui48
+from netaddr.strategy.eui64 import eui64_base
+
+class BaseIdentifier:
+    def __init__(self) -> None: ...
+    def __int__(self) -> int: ...
+    def __long__(self) -> int: ...
+    def __oct__(self) -> str: ...
+    def __hex__(self) -> str: ...
+    def __index__(self) -> int: ...
+
+class OUI(BaseIdentifier):
+    records: list[dict[str, object]]
+    def __init__(self, oui: str | int) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    @property
+    def reg_count(self) -> int: ...
+    def registration(self, index: int = ...) -> DictDotLookup: ...
+
+class IAB(BaseIdentifier):
+    IAB_EUI_VALUES: ClassVar[tuple[int, int]]
+    @classmethod
+    def split_iab_mac(cls, eui_int: int, strict: bool = ...) -> tuple[int, int]: ...
+    record: dict[str, object]
+    def __init__(self, iab: str | int, strict: bool = ...) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def registration(self) -> DictDotLookup: ...
+
+class EUI(BaseIdentifier):
+    def __init__(
+        self, addr: EUI | int | str, version: int | None = ..., dialect: type[mac_eui48] | type[eui64_base] | None = ...
+    ) -> None: ...
+    @property
+    def value(self) -> int: ...
+    @value.setter
+    def value(self, value: str | SupportsInt | SupportsIndex) -> None: ...
+    @property
+    def dialect(self) -> type[mac_eui48] | type[eui64_base]: ...
+    @dialect.setter
+    def dialect(self, value: type[mac_eui48] | type[eui64_base] | None) -> None: ...
+    @property
+    def oui(self) -> OUI: ...
+    @property
+    def ei(self) -> str: ...
+    def is_iab(self) -> bool: ...
+    @property
+    def iab(self) -> IAB | None: ...
+    @property
+    def version(self) -> Literal[48, 64]: ...
+    @overload
+    def __getitem__(self, idx: int) -> int: ...
+    @overload
+    def __getitem__(self, idx: slice) -> list[int]: ...
+    @overload
+    def __getitem__(self, idx: int | slice) -> int | list[int]: ...
+    def __setitem__(self, idx: int, value: int) -> None: ...
+    def __hash__(self) -> int: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __lt__(self, other: EUI | int | str) -> bool: ...
+    def __le__(self, other: EUI | int | str) -> bool: ...
+    def __gt__(self, other: EUI | int | str) -> bool: ...
+    def __ge__(self, other: EUI | int | str) -> bool: ...
+    def bits(self, word_sep: str | None = ...) -> str: ...
+    @property
+    def packed(self) -> bytes: ...
+    @property
+    def words(self) -> tuple[int, ...]: ...
+    @property
+    def bin(self) -> str: ...
+    def eui64(self: Self) -> Self: ...
+    def modified_eui64(self: Self) -> Self: ...
+    def ipv6(self, prefix: str | SupportsInt | SupportsIndex) -> IPAddress: ...
+    def ipv6_link_local(self) -> IPAddress: ...
+    @property
+    def info(self) -> DictDotLookup: ...
+    def format(self, dialect: type[mac_eui48] | type[eui64_base] | None = ...) -> str: ...

stubs/netaddr/netaddr/eui/ieee.pyi

@@ -0,0 +1,33 @@
+import _csv
+from _typeshed import StrOrBytesPath
+from collections.abc import Iterable
+from typing import Any, BinaryIO, TextIO
+from typing_extensions import TypeAlias
+
+from netaddr.core import Publisher, Subscriber
+
+_INDEX: TypeAlias = dict[int, list[tuple[int, int]]]
+OUI_INDEX: _INDEX
+IAB_INDEX: _INDEX
+
+class FileIndexer(Subscriber):
+    writer: _csv._writer
+    def __init__(self, index_file: TextIO | StrOrBytesPath | int) -> None: ...
+    def update(self, data: Iterable[Any]) -> None: ...
+
+class OUIIndexParser(Publisher):
+    fh: BinaryIO
+    def __init__(self, ieee_file: BinaryIO | StrOrBytesPath | int) -> None: ...
+    def parse(self) -> None: ...
+
+class IABIndexParser(Publisher):
+    fh: BinaryIO
+    def __init__(self, ieee_file: BinaryIO | StrOrBytesPath | int) -> None: ...
+    def parse(self) -> None: ...
+
+def create_index_from_registry(
+    registry_fh: BinaryIO | StrOrBytesPath | int, index_path: StrOrBytesPath, parser: type[OUIIndexParser] | type[IABIndexParser]
+) -> None: ...
+def create_indices() -> None: ...
+def load_index(index: _INDEX, fp: Iterable[bytes]) -> None: ...
+def load_indices() -> None: ...

stubs/netaddr/netaddr/fbsocket.pyi

@@ -0,0 +1,8 @@
+from typing_extensions import Literal
+
+AF_INET: Literal[2]
+AF_INET6: Literal[10]
+
+def inet_ntoa(packed_ip: bytes) -> str: ...
+def inet_ntop(af: int, packed_ip: bytes) -> str: ...
+def inet_pton(af: int, ip_string: str) -> str: ...