Add type hints and update packaging

netifaces-stubs/__init__.pyi

@@ -0,0 +1,99 @@
+from typing import Final, overload, type_check_only
+
+from typing_extensions import Literal, TypeAlias
+
+AF_12844: Final[int]
+AF_APPLETALK: Final[int]
+AF_ASH: Final[int]
+AF_ATM: Final[int]
+AF_ATMPVC: Final[int]
+AF_ATMSVC: Final[int]
+AF_AX25: Final[int]
+AF_BAN: Final[int]
+AF_BLUETOOTH: Final[int]
+AF_BRIDGE: Final[int]
+AF_DATAKIT: Final[int]
+AF_DECnet: Final[int]
+AF_CCITT: Final[int]
+AF_CHAOS: Final[int]
+AF_CLUSTER: Final[int]
+AF_CNT: Final[int]
+AF_COIP: Final[int]
+AF_DLI: Final[int]
+AF_ECONET: Final[int]
+AF_ECMA: Final[int]
+AF_FILE: Final[int]
+AF_FIREFOX: Final[int]
+AF_HYLINK: Final[int]
+AF_IMPLINK: Final[int]
+AF_INET: Final[int]
+AF_INET6: Final[int]
+AF_IPX: Final[int]
+AF_IRDA: Final[int]
+AF_ISDN: Final[int]
+AF_ISO: Final[int]
+AF_KEY: Final[int]
+AF_LAT: Final[int]
+AF_LINK: Final[int]
+AF_NATM: Final[int]
+AF_NETBEUI: Final[int]
+AF_NETBIOS: Final[int]
+AF_NETDES: Final[int]
+AF_NETGRAPH: Final[int]
+AF_NETLINK: Final[int]
+AF_NETROM: Final[int]
+AF_NDRV: Final[int]
+AF_NS: Final[int]
+AF_PACKET: Final[int]
+AF_PPP: Final[int]
+AF_PPPOX: Final[int]
+AF_PUP: Final[int]
+AF_ROSE: Final[int]
+AF_ROUTE: Final[int]
+AF_SECURITY: Final[int]
+AF_SIP: Final[int]
+AF_SNA: Final[int]
+AF_SYSTEM: Final[int]
+AF_UNIX: Final[int]
+AF_UNKNOWN1: Final[int]
+AF_UNSPEC: Final[int]
+AF_VOICEVIEW: Final[int]
+AF_WANPIPE: Final[int]
+AF_X25: Final[int]
+IN6_IFF_AUTOCONF: Final[int]
+IN6_IFF_TEMPORARY: Final[int]
+IN6_IFF_DYNAMIC: Final[int]
+IN6_IFF_OPTIMISTIC: Final[int]
+IN6_IFF_SECURED: Final[int]
+
+address_families: Final[dict[int, str]]
+version: Final[str]
+
+# In reality, gateways() returns a normal `dict`. However, the
+# current type system cannot accurately express a `dict` that has
+# one literal string key that maps to one type and `int` keys that
+# map to another. Without these aliases and subclass, the closest we
+# could get would be this monstrosity:
+#
+# dict[int | Literal["default"], list[tuple[str, str, bool]] | dict[int, tuple[str, str]]]
+
+_Gateway: TypeAlias = tuple[str, str, bool]
+_DefaultGateway: TypeAlias = tuple[str, str]
+
+_KT: TypeAlias = int | Literal["default"]
+_VT: TypeAlias = list[_Gateway] | dict[int, _DefaultGateway]
+
+@type_check_only
+class _Gateways(dict[_KT, _VT]):
+    @overload
+    def __getitem__(self, key: Literal["default"], /) -> dict[int, _DefaultGateway]: ...
+    @overload
+    def __getitem__(self, key: int, /) -> list[_Gateway]: ...
+    # We need this last overload or else everyone complains
+    # about the signature being incompatible with `Mapping`
+    @overload
+    def __getitem__(self, key: _KT, /) -> _VT: ...
+
+def gateways() -> _Gateways: ...
+def ifaddresses(ifname: str, /) -> dict[int, list[dict[str, str]]]: ...
+def interfaces() -> list[str]: ...

netifaces.c

@@ -2537,16 +2537,34 @@ gateways (PyObject *self)
 
 /* -- Python Module --------------------------------------------------------- */
 
+// On Python >= 3.4, the function signature shown by help() can be customized if the 
+// function signature is followed by --\n\n
+// https://stackoverflow.com/a/41245451
+#if PY_MAJOR_VERSION == 3 && PY_MINOR_VERSION >= 4
+#define SIGNATURE_SEPARATOR "--\n"
+#else
+#define SIGNATURE_SEPARATOR ""
+#endif
+
 static PyMethodDef methods[] = {
   { "ifaddresses", (PyCFunction)ifaddrs, METH_VARARGS,
+    "ifaddresses(ifaddress, /)\n"
+    SIGNATURE_SEPARATOR
+    "\n"
     "Obtain information about the specified network interface.\n"
 "\n"
 "Returns a dict whose keys are equal to the address family constants,\n"
 "e.g. netifaces.AF_INET, and whose values are a list of addresses in\n"
 "that family that are attached to the network interface." },
   { "interfaces", (PyCFunction)interfaces, METH_NOARGS,
+    "interfaces()\n"
+    SIGNATURE_SEPARATOR
+    "\n"
     "Obtain a list of the interfaces available on this machine." },
   { "gateways", (PyCFunction)gateways, METH_NOARGS,
+    "gateways()\n"
+    SIGNATURE_SEPARATOR
+    "\n"
     "Obtain a list of the gateways on this machine.\n"
 "\n"
 "Returns a dict whose keys are equal to the address family constants,\n"

pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"

setup.cfg

@@ -1,7 +1,38 @@
+[metadata]
+name = netifaces
+version = 0.10.9
+author = Alastair Houghton
+author_email = [email protected]
+url = https://github.com/al45tair/netifaces
+description = Portable network interface information
+long_description_content_type = text/x-rst
+long_description = file: README.rst
+license = MIT License
+license_files =
+    LICENSE
+classifiers =
+    Development Status :: 4 - Beta
+    Intended Audience :: Developers
+    License :: OSI Approved :: MIT License
+    Topic :: System :: Networking
+    Programming Language :: Python
+    Programming Language :: Python :: 2
+    Programming Language :: Python :: 2.7
+    Programming Language :: Python :: 3
+    Programming Language :: Python :: 3.4
+    Programming Language :: Python :: 3.5
+    Programming Language :: Python :: 3.6
+    Programming Language :: Python :: 3.7
+    Programming Language :: Python :: 3.8
+
+[options]
+packages = netifaces-stubs
+python_requires = >=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*
+
+[options.package_data]
+* = *.pyi, py.typed
+
 [egg_info]
 tag_build = 
 tag_date = 0
 tag_svn_revision = 0
-
-[metadata]
-license_file = LICENSE