netimps 0.0.0__tar.gz

netimps-0.0.0/.gitignore

@@ -0,0 +1,38 @@
+# Agent configs / private notes — never tracked in this repo
+.agents
+*.local.md
+CLAUDE*
+.claude/
+
+# Virtualenvs
+.venv*/
+venv/
+env/
+.env/
+
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Test / coverage / type-checker caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+site/

netimps-0.0.0/AGENTS.md

@@ -0,0 +1,181 @@
+# netimps
+
+A **small, self-contained network-utilities library** — a thin, typed layer over
+the standard library's `ipaddress`, native cross-platform interface discovery,
+and a handful of host helpers (DNS lookup, ping). One flat import surface, one
+runtime dependency (`dnspython`, used only by `resolve`), and behaviour that
+stays faithful to the stdlib.
+
+```python
+import netimps
+from netimps import IPNetwork, MACAddress, parse
+
+for iface in netimps.get_interfaces():
+    print(iface.name, iface.mac, iface.mtu, [str(ip) for ip in iface.ips])
+
+parse("10.0.0.5/24", IPNetwork)            # IPv4Network('10.0.0.0/24')
+netimps.get_source_ip("8.8.8.8")           # the address that actually reaches it
+netimps.tcp_check("example.com", 443)      # True
+netimps.resolve("example.com")             # [IPv4Address(...)]  ([] on failure)
+netimps.ping("8.8.8.8").rtt_ms             # 9.0
+```
+
+- **Interface discovery, no dependencies** — `get_interfaces()` gives adapter
+  names, MACs, MTU and *real* prefix lengths on Linux, macOS/BSD and Windows,
+  via `ctypes` bindings to `getifaddrs(3)` / `GetAdaptersAddresses`. Results are
+  normalised across platforms; native leftovers are opt-in via `raw=True`.
+- **One parsing entry point** — `parse(value, type)`, plus non-raising
+  `try_parse` and boolean `is_valid`. `IPAddress`/`IPInterface`/`IPNetwork` are
+  the v4/v6 unions you annotate with *and* the types you parse into.
+- **`MACAddress`** — colon/hyphen/dot/bare plus `int`/`bytes`, hashable and
+  ordered, with `.packed`, `.oui`, `.is_multicast`, `.is_local`,
+  `.as_str(sep, upper=)` and `is_valid`/`try_parse` classmethods.
+- **Socket helpers** — `get_source_ip`, `get_free_port`, `tcp_check`,
+  `wait_for_port`: the four every network tool rewrites.
+- **Routing and MTU** — `get_route` (first hop, unprivileged), `hop_count`
+  (raw sockets or traceroute fallback), `discover_mtu` / `get_pmtu`, `Interface.mtu`.
+- **CIDR maths and host parsing** — `collapse`, `subtract` (absent from
+  `ipaddress`), and `normalize_host` with correct IPv6 bracket handling.
+- **Scanning** — concurrent `scan_ports` / `scan_hosts`, ports addressable by
+  scheme name.
+- **Multicast** — `multicast_socket`, `join_group`, `leave_group`, wrapping the
+  setup whose failure modes are silent.
+- **DNS and ping** — `resolve()` returning native types; `ping()` returning a
+  `PingResult` with RTT and TTL that stays truthy.
+
+## Install
+
+```bash
+pip install netimps
+```
+
+Requires Python 3.9+. Runtime dependency: `dnspython` (used only inside
+`resolve`).
+
+> **This file is development documentation** — layout, testing, CI, release.
+> It is deliberately **not shipped** in the wheel. The library-usage reference
+> is `src/netimps/AGENTS.md`, which *is* shipped and must stay self-contained
+> (no repo-relative links, since an installed consumer has no repo).
+
+## Code layout
+
+```
+src/netimps/
+├── __init__.py   # the public surface: generic parse/try_parse/is_valid
+├── _ip.py        # private: IP type aliases, builder tables, IP helpers
+├── _mac.py       # private: MACAddress value type
+├── _scheme.py    # private: scheme <-> port registry
+├── _scan.py      # private: concurrent port/host scanning
+├── _multicast.py # private: group membership and socket setup
+├── _ifaddrs.py   # private: ctypes getifaddrs/GetAdaptersAddresses bindings
+├── _sockets.py   # private: source IP, free port, tcp/wait, route, hops, MTU
+├── _dns.py       # private: resolve() over dnspython
+├── _ping.py      # private: ping() over the platform binary
+└── py.typed      # PEP 561 marker — the package ships inline type hints
+```
+
+**The import surface is still flat** — everything is re-exported from
+`netimps`, and the `_`-prefixed modules are implementation detail. Do not
+import them directly from outside the package.
+
+`__init__` imports the submodules **last**, because several of them call back
+into it (`parse`, `try_parse`, `MACAddress`); those back-references are
+function-local imports for the same reason. Everything importable from
+`netimps` is declared in `__all__` at the top of `__init__.py`.
+
+## Entry points
+
+See **`src/netimps/AGENTS.md`** for the header-file-style public API (every
+export with its signature, arguments, return contract, and gotchas). Quick
+map:
+
+| Name | Purpose |
+| --- | --- |
+| `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
+| `IPAddressLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `IPv4Address`, `IPv4Interface`, `IPv4Network`, `IPv6Address`, `IPv6Interface`, `IPv6Network` | stdlib concrete-type re-exports |
+| `parse`, `try_parse`, `is_valid` | build a type from a value (raising / `None` / `bool`) |
+| `MACAddress` | parse / classify / render MAC addresses |
+| `get_interfaces`, `Interface`, `iter_addresses` | native cross-platform NIC discovery |
+| `get_ip`, `is_link_scoped` | address resolution and scope classification |
+| `collapse`, `subtract` | CIDR set maths |
+| `normalize_host` | `host:port` splitting, IPv6-aware |
+| `get_default_port`, `get_default_scheme`, `register_port` | scheme ↔ port registry |
+| `resolve` | DNS lookup → native records (`[]` on failure) |
+| `ping`, `PingResult` | reachability with RTT and TTL |
+| `bind`, `bind_error_hint`, `interface_for` | socket creation and diagnosis |
+| `get_source_ip`, `get_free_port`, `tcp_check`, `wait_for_port` | socket helpers |
+| `UdpEndpoint`, `Datagram` | UDP receive with arrival interface (`IP_PKTINFO`) |
+| `Host` | hostname-or-address value type |
+| `retry`, `backoff_delays` | bounded retry with exponential backoff |
+| `APIPA`, `LOOPBACK_V4`, `LOOPBACK_V6`, `LINK_LOCAL_V6` | named networks |
+| `get_route`, `Route`, `hop_count` | routing and distance |
+| `discover_mtu`, `get_pmtu`, `get_tcp_mss` | path MTU by ICMP/UDP/TCP, the kernel's cached guess, or the negotiated MSS |
+| `scan_ports`, `scan_hosts`, `PORT_RANGES` | concurrent scanning |
+| `multicast_socket`, `join_group`, `leave_group`, `is_multicast` | multicast |
+| `HOST_DN` | `platform.node()` of the running host, captured at import time |
+
+## Working here
+
+- **Don't collapse the per-platform `sockaddr` layouts** in `_ifaddrs.py`.
+  macOS/BSD have a leading `sa_len` byte Linux lacks; using the Linux layout on
+  BSD decodes `AF_INET` as `512` and *silently* drops every address instead of
+  raising — a Linux-only CI stays green while Mac users lose data.
+- **`is_loopback` is derived from addresses, never names** (`lo` / `lo0` /
+  `Loopback Pseudo-Interface 1` share no spelling).
+- The ctypes paths can't be asserted against fixed values, so
+  `tests/test_interfaces.py` checks invariants plus the pure helpers and the
+  fallback, which *are* exactly testable.
+- Tests must never hit the network — `tests/test_net.py` fakes `dns.resolver`
+  and `subprocess.run` throughout. `test_scan.py` and `test_sockets.py` use
+  loopback only.
+- **`_ip` is imported *before* the definitions** in `__init__`, unlike the other
+  submodules which are imported last. `parse()` uses `IPAddress` as a default
+  argument, and defaults evaluate at definition time.
+- **Windows `ping` exits 0 for "TTL expired in transit."** Anything inferring
+  success from the exit code alone is wrong; match the reply address instead,
+  never the localised prose.
+- **Check for silent platform gaps before adding a socket option.** `IP_MTU`,
+  `IP_MTU_DISCOVER`, `IP_DONTFRAG` and `SO_REUSEPORT` do not exist on Windows;
+  binding a multicast socket to the group address fails there too.
+- **Windows exposes no cached path MTU.** Already investigated, so do not
+  re-derive it: `MIB_IPFORWARDROW.dwForwardMtu` reads 0 (unsupported), and
+  `MIB_IPFORWARD_ROW2` has no MTU field. `Interface.mtu` is the link MTU;
+  `discover_mtu` probing is the only way to get a path MTU there.
+- **`GetBestRoute`, not `GetIpForwardTable`.** It asks Windows which route it
+  would pick, so the kernel does longest-prefix matching. The POSIX side has no
+  equivalent and must parse `/proc/net/route` by hand — which is where the
+  loopback bug came from, since that file omits loopback entirely.
+- Run `black src/ tests/` before committing; CI uses `--check`.
+
+## Develop
+
+```bash
+python -m venv .venv/dev
+.venv/dev/Scripts/pip install -e ".[dev]"   # POSIX: .venv/dev/bin/pip
+.venv/dev/Scripts/pytest -q                 # POSIX: .venv/dev/bin/pytest -q
+```
+
+Tests live in `tests/` (`test_ip.py`, `test_mac.py`, `test_net.py`,
+`test_interfaces.py`) and run via `pytest -q` from a checkout;
+`pyproject.toml` puts `src/` on the path. Run against **3.9 and 3.14** — 3.9 is
+the floor, so no unquoted `X | Y` unions at runtime.
+
+Code is formatted with **black** (`target-version = py39`, configured in
+`pyproject.toml`; installed by the `dev` extra):
+
+```bash
+.venv/dev/Scripts/black src/ tests/          # format
+.venv/dev/Scripts/black --check src/ tests/  # verify, for CI
+```
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the
+release workflow: test gate → build → publish (PyPI) → docs deploy. Package
+builds locally with `hatchling`.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

netimps-0.0.0/CHANGELOG.md

@@ -0,0 +1,70 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.0.0] - 2026-07-22
+
+Initial release.
+
+Earlier version numbers appear in this project's git history but were never
+tagged or published, so there is no upgrade path to describe -- everything
+below is simply what the package contains.
+
+### Added
+
+- **Interface discovery** -- `get_interfaces()` reports adapter names, MACs,
+  MTU and *real* prefix lengths on Linux, macOS/BSD and Windows, via `ctypes`
+  bindings to `getifaddrs(3)` and `GetAdaptersAddresses`. No third-party
+  dependency. `Interface.is_loopback` is derived from the addresses rather than
+  the name, since `lo`, `lo0` and `Loopback Pseudo-Interface 1` share no
+  spelling. `Interface.primary_ip()` picks one entry; `iter_addresses()` is the
+  flattened per-address view.
+- **Types and parsing** -- `IPAddress`/`IPInterface`/`IPNetwork` union aliases
+  to annotate with, and one `parse(value, type, **kwargs)` entry point with
+  non-raising `try_parse` and boolean `is_valid` siblings. Concrete types are
+  strict about family; networks are non-strict about host bits by default.
+- **`MACAddress`** -- colon/hyphen/dot/bare plus `int`/`bytes`, hashable and
+  ordered, with `.packed`, `.oui`, `.is_multicast`, `.is_local` and
+  case-selectable rendering. A value type exposing `.packed`, not a `bytes`
+  subclass, matching how `ipaddress` models addresses.
+- **Socket helpers** -- `bind()`, `bind_error_hint()`, `interface_for()`,
+  `get_source_ip()`, `get_free_port()`, `tcp_check()`, `wait_for_port()`.
+- **`UdpEndpoint`** -- UDP receive reporting which interface a datagram arrived
+  on via `IP_PKTINFO`, degrading where `recvmsg` does not exist.
+- **Routing and MTU** -- `get_route()` (first hop, unprivileged), `hop_count()`
+  (raw sockets or a traceroute fallback, so it works without elevation),
+  `discover_mtu()` (measures the real path -- `method="icmp"` with DF-flagged
+  pings, `"udp"` with datagrams, or `"tcp"` deriving from the negotiated MSS
+  since TCP cannot be probed), `get_pmtu()` (the kernel's cached answer, usually
+  `None`), `get_tcp_mss()`, and `Interface.mtu`. Header arithmetic is
+  family-aware: IPv6 adds 20 bytes over IPv4, and assuming v4 on a v6 path
+  under-reports by exactly that.
+- **CIDR maths and host parsing** -- `collapse()`, `subtract()` (absent from
+  `ipaddress`), and `normalize_host()`, which keeps `"::1"` an address rather
+  than host `"::"` port `1`.
+- **Scheme/port registry** -- `get_default_port()`, `get_default_scheme()`,
+  `register_port()`.
+- **DNS** -- `resolve()` returning native types (`A`/`AAAA` as `ipaddress`
+  objects), `[]` on a genuine lookup failure, and `ValueError` for a malformed
+  query rather than a silent empty result.
+- **`ping()`** -- returns a `PingResult` with round-trip time and TTL that stays
+  truthy. `method="icmp"|"tcp"|"udp"` reaches hosts through firewalls that drop
+  echo; all three ask "is the *host* up?", so a TCP refusal or an ICMP
+  port-unreachable counts as success. `tcp_check` remains the "is the *service*
+  up?" question, where a refusal is a failure. `ttl=` behaves identically on every platform, because Windows `ping`
+  exits 0 for "TTL expired in transit" and the reply address is verified
+  instead of the exit code.
+- **Scanning** -- concurrent `scan_ports()` / `scan_hosts()`, ports addressable
+  by scheme name.
+- **Multicast** -- `multicast_socket()`, `join_group()`, `leave_group()`,
+  wrapping a setup whose failure modes are otherwise silent.
+- **`Host`**, **`retry()`/`backoff_delays()`**, and the named networks `APIPA`,
+  `LOOPBACK_V4`, `LOOPBACK_V6`, `LINK_LOCAL_V6`.
+
+[Unreleased]: https://github.com/jose-pr/netimps/compare/v0.0.0...HEAD
+[0.0.0]: https://github.com/jose-pr/netimps/releases/tag/v0.0.0

netimps-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+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.

netimps-0.0.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: netimps
+Version: 0.0.0
+Summary: Small, self-contained network utilities: IP/MAC types, DNS lookup, ping, NIC discovery
+Project-URL: Homepage, https://github.com/jose-pr/netimps
+Project-URL: Documentation, https://jose-pr.github.io/netimps/
+Project-URL: Issues, https://github.com/jose-pr/netimps/issues
+Author: Jose A.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: dnspython
+Provides-Extra: dev
+Requires-Dist: black; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# netimps
+
+[![Version](https://img.shields.io/pypi/v/netimps.svg)](https://pypi.org/project/netimps/)
+[![Python versions](https://img.shields.io/pypi/pyversions/netimps.svg)](https://pypi.org/project/netimps/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/netimps/test.yml)](https://github.com/jose-pr/netimps/actions/workflows/test.yml)
+
+**The network utilities every tool ends up rewriting** — interface discovery,
+"which is my IP", reachability checks, CIDR maths, host:port parsing, DNS,
+ping, scanning and multicast — as one typed, flat-import library.
+
+Built on the standard library: the only runtime dependency is `dnspython`, and
+only `resolve()` uses it. Interface enumeration, routing and multicast are
+`ctypes` bindings to the platform's own APIs, so there is nothing to compile
+and no wheel to miss for your platform.
+
+## Features
+
+- **Interface discovery, no dependencies** — `get_interfaces()` gives adapter
+  names, MACs, MTU and **real prefix lengths** on Linux, macOS/BSD and Windows,
+  via `getifaddrs(3)` / `GetAdaptersAddresses`. No `ifaddr` required.
+- **One parsing entry point** — `parse(value, type)` with non-raising
+  `try_parse` and boolean `is_valid` siblings, all typed so a checker narrows
+  the result.
+- **`MACAddress`** — colon/hyphen/dot/bare plus `int`/`bytes`, hashable and
+  ordered, with `.oui`, `.is_multicast`, `.is_local` and case-selectable
+  rendering.
+- **The socket helpers everyone rewrites** — `get_source_ip`, `get_free_port`,
+  `tcp_check`, `wait_for_port`.
+- **Routing and MTU** — `get_route` (first hop, unprivileged), `hop_count`
+  (raw sockets *or* traceroute fallback), `discover_mtu` / `get_pmtu`, `Interface.mtu`.
+- **CIDR set maths** — `collapse` and `subtract`, the latter missing from
+  `ipaddress` entirely.
+- **`normalize_host`** — `host:port` splitting that gets IPv6 brackets right.
+- **Scanning** — concurrent `scan_ports` / `scan_hosts`.
+- **Socket setup** — `bind()` with the options named, `UdpEndpoint` for UDP
+  servers that need to know which interface a datagram arrived on, and
+  `retry()` for the backoff loop everyone writes without jitter.
+- **Multicast** — `multicast_socket` handling the join dance whose failure
+  modes are otherwise silent.
+- **DNS and ping** — `resolve()` returning native types; `ping()` returning
+  round-trip time and TTL, not just a boolean.
+
+## Installation
+
+```bash
+pip install netimps
+```
+
+Requires Python 3.9+.
+
+## Quick start
+
+```python
+import netimps
+from netimps import IPAddress, IPNetwork, MACAddress, parse
+
+# Interfaces: names, MACs, MTU and real prefixes on every OS
+for iface in netimps.get_interfaces():
+    print(iface.name, iface.mac, iface.mtu, [str(ip) for ip in iface.ips])
+    # 'Wi-Fi'  00:00:5e:00:53:01  1500  ['192.0.2.10/24', 'fe80::.../64']
+
+# Types annotate; parse builds
+def route(dst: IPAddress, via: IPNetwork) -> None: ...
+
+parse("10.0.0.5")                        # IPv4Address('10.0.0.5')
+parse("10.0.0.5/24", IPNetwork)          # IPv4Network('10.0.0.0/24')
+netimps.try_parse("nope", IPAddress)     # None
+netimps.is_valid("::1", IPAddress)       # True
+
+# Which of my addresses actually reaches that host?
+netimps.get_source_ip("8.8.8.8")         # IPv4Address('192.0.2.10')
+netimps.get_route("8.8.8.8").gateway     # IPv4Address('192.0.2.1')
+
+# Honest reachability, and waiting for a service
+netimps.tcp_check("example.com", 443)              # True
+netimps.wait_for_port("localhost", 5432, timeout=60)
+
+# CIDR set maths
+netimps.subtract(["10.0.0.0/24"], ["10.0.0.64/26"])
+# [IPv4Network('10.0.0.0/26'), IPv4Network('10.0.0.128/25')]
+
+# host:port, including the IPv6 case people get wrong
+netimps.normalize_host("[::1]:8080")     # ('::1', 8080)
+netimps.normalize_host("::1")            # ('::1', None)  -- not port 1
+
+# MAC addresses
+mac = MACAddress("AA-BB-CC-DD-EE-FF")
+mac.as_str("-", upper=True)              # 'AA-BB-CC-DD-EE-FF'
+mac.is_local, mac.oui.hex()              # (True, 'aabbcc') -- AA has the U/L bit
+
+# DNS returns native types
+netimps.resolve("example.com")[0].is_global   # an IPv4Address, not a str
+netimps.resolve("example.com", "txt")         # ['v=spf1 -all']  -- unquoted
+
+# ping carries the details, and can use TCP or UDP where ICMP is blocked
+result = netimps.ping("8.8.8.8")
+result.ok, result.rtt_ms, result.ttl     # (True, 9.0, 119)
+netimps.ping("8.8.8.8", method="tcp", port=53)   # times the handshake
+
+# Path MTU, measured rather than guessed
+netimps.discover_mtu("8.8.8.8")                       # 1500
+netimps.discover_mtu("10.0.0.5", method="udp", port=9999)
+netimps.get_tcp_mss("example.com", 443)               # 1460
+
+# Scanning and multicast
+netimps.scan_ports("192.168.1.1", ["ssh", "https"])   # [22, 443]
+sock = netimps.multicast_socket("224.0.0.251", 5353)  # mDNS listener
+
+# Server-side: bind with the options named, and know where packets came from
+server = netimps.bind("", 6767, broadcast=True)
+endpoint = netimps.UdpEndpoint(server)
+
+# Retry with backoff and jitter
+netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
+```
+
+## API overview
+
+| Name | Purpose |
+| --- | --- |
+| `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
+| `IPAddressLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `IPv4Address`, `IPv4Interface`, ... | stdlib concrete-type re-exports |
+| `parse`, `try_parse`, `is_valid` | build a type from a value (raising / `None` / `bool`) |
+| `MACAddress` | parse / classify / render MAC addresses |
+| `get_interfaces`, `Interface`, `iter_addresses` | native cross-platform NIC discovery |
+| `get_ip`, `is_link_scoped` | address resolution and scope classification |
+| `collapse`, `subtract` | CIDR set maths |
+| `normalize_host` | `host:port` splitting, IPv6-aware |
+| `get_default_port`, `get_default_scheme`, `register_port` | scheme ↔ port registry |
+| `resolve` | DNS lookup → native records (`[]` on failure) |
+| `ping`, `PingResult` | reachability with RTT and TTL |
+| `bind`, `bind_error_hint`, `interface_for` | socket creation and diagnosis |
+| `get_source_ip`, `get_free_port`, `tcp_check`, `wait_for_port` | socket helpers |
+| `UdpEndpoint`, `Datagram` | UDP receive with arrival interface (`IP_PKTINFO`) |
+| `Host` | hostname-or-address value type |
+| `retry`, `backoff_delays` | bounded retry with exponential backoff |
+| `APIPA`, `LOOPBACK_V4`, `LOOPBACK_V6`, `LINK_LOCAL_V6` | named networks |
+| `get_route`, `Route`, `hop_count` | routing and distance |
+| `discover_mtu`, `get_pmtu`, `get_tcp_mss` | path MTU by ICMP/UDP/TCP, the kernel's cached guess, or the negotiated MSS |
+| `scan_ports`, `scan_hosts`, `PORT_RANGES` | concurrent scanning |
+| `multicast_socket`, `join_group`, `leave_group`, `is_multicast` | multicast |
+| `HOST_DN` | `platform.node()`, captured at import time |
+
+Full per-export reference, with contracts and gotchas, lives in
+[`src/netimps/AGENTS.md`](src/netimps/AGENTS.md).
+
+## Design notes
+
+A few behaviours are deliberate and worth knowing:
+
+- **`Interface.is_loopback` is computed from addresses, not names** — `lo`,
+  `lo0` and `Loopback Pseudo-Interface 1` share no spelling.
+- **Concrete types are strict about family.** `parse("::1", IPAddress)` works;
+  `parse("::1", IPv4Address)` raises rather than quietly returning v6.
+- **Networks parse non-strict by default**, so `10.0.0.5/24` normalises instead
+  of raising. Pass `strict=True` for stdlib behaviour.
+- **`resolve` raises on a malformed query** rather than returning `[]` — a
+  typo'd record type should not look like "no such record".
+- **`ping(ttl=...)` behaves the same on every OS.** Windows `ping` exits `0`
+  for "TTL expired in transit", so the reply address is verified instead of
+  trusting the exit code.
+- **`hop_count` works unprivileged**, falling back to the system traceroute
+  when a raw socket is unavailable.
+- **`discover_mtu` measures; `get_pmtu` only reports what the kernel cached.**
+  The latter is usually `None`, and always `None` on Windows. On one real host
+  the local link was 9000 and the true path MTU 1500 — only probing found it.
+
+## Development
+
+```bash
+python -m venv .venv/dev
+.venv/dev/Scripts/pip install -e ".[dev]"   # POSIX: .venv/dev/bin/pip
+.venv/dev/Scripts/pytest -q
+.venv/dev/Scripts/black src/ tests/
+```
+
+Tested on Python 3.9 (the floor) and 3.14.
+
+### Releasing
+
+This project follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a tag matching `v*` triggers the release
+workflow: test gate → build → publish → docs deploy.
+
+## License
+
+MIT — see [LICENSE](LICENSE).