netimps 0.0.2__tar.gz → 0.2.0__tar.gz

{netimps-0.0.2 → netimps-0.2.0}/AGENTS.md

@@ -2,9 +2,10 @@
 
 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.
+and a handful of host helpers (DNS lookup, ping). One flat import surface, no
+hard runtime dependencies (`resolve()` chains `dnspython`/OS-resolver/
+`nslookup` backends, using whichever is available -- `dnspython` is optional,
+via the `dns` extra), and behaviour that stays faithful to the stdlib.
 
 ```python
 import netimps
@@ -46,11 +47,11 @@ netimps.ping("8.8.8.8").rtt_ms             # 9.0
 ## Install
 
 ```bash
-pip install netimps
+pip install netimps          # no hard dependencies
+pip install netimps[dns]     # plus dnspython, for resolve()'s fullest backend
 ```
 
-Requires Python 3.9+. Runtime dependency: `dnspython` (used only inside
-`resolve`).
+Requires Python 3.9+. No hard runtime dependencies.
 
 > **This file is development documentation** — layout, testing, CI, release.
 > It is deliberately **not shipped** in the wheel. The library-usage reference
@@ -71,7 +72,7 @@ src/netimps/
 ├── _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
+├── _dns.py       # private: resolve() chaining dnspython/system/nslookup backends
 ├── _ping.py      # private: ping() over the platform binary
 └── py.typed      # PEP 561 marker — the package ships inline type hints
 ```
@@ -94,7 +95,7 @@ map:
 | Name | Purpose |
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
-| `IPAddressLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `IPAddressLike`, `IPInterfaceLike`, `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 |
@@ -105,7 +106,7 @@ map:
 | `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 |
+| `bind`, `bind_error_hint`, `interface_for`, `interfaces_for`, `is_local_address` | socket creation and local membership |
 | `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 |

{netimps-0.0.2 → netimps-0.2.0}/CHANGELOG.md

@@ -7,6 +7,74 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-07-29
+
+### Added
+
+- **Three independently callable DNS backends**, plus `resolve()` chaining
+  them: `resolve_dnspython()` (the original `dnspython`-backed
+  implementation, every record type), `resolve_system()`
+  (`socket.getaddrinfo()` -- hosts file, NSS, OS resolver cache, address
+  records only), and `resolve_nslookup()` (shells out to `nslookup`, parses
+  both BIND-style and Windows-style output, address records only). `resolve()`
+  now tries `["dnspython", "system", "nslookup"]` in order by default and
+  returns the first definitive answer, skipping/falling through backends that
+  can't serve the request (non-address `rdtype`, missing binary, `dnspython`
+  not installed). A custom order/subset is available via
+  `resolve(..., backends=[...])` (or a single name as a plain string).
+- `resolve()` (and all three backends) gain a `search` parameter for the
+  system resolver's search list (`resolv.conf`'s `search`/`domain`
+  directive, or the Windows per-adapter DNS suffix list). It defaults to
+  `True`, so an unqualified name like `resolve("db1")` is expanded the way
+  `ping db1` would be; `search=False` looks the name up literally (as a
+  fully-qualified name, so the OS resolver's own search-list logic doesn't
+  kick in either), and a list of domain names tries exactly those suffixes
+  instead of the system list.
+- `dnspython` is now an **optional** dependency (`pip install netimps[dns]`),
+  since `resolve()` can fall back to `resolve_system()`/`resolve_nslookup()`
+  without it. The CLI's `resolve` subcommand now reports a missing-backend
+  failure as a clean CLI error rather than an uncaught exception.
+
+### Changed
+
+- **`resolve()`'s default behavior for unqualified names.** Previously an
+  unqualified `query` was only ever looked up as-is; it now also tries the
+  system resolver's search list first (see `search` above). Pass
+  `search=False` to keep the old literal-only behavior. `ns=None` already
+  used the system resolver's nameservers; an invalid `ns=` now raises before
+  any query is attempted rather than silently falling back to the system
+  default.
+- **`resolve()` is no longer purely `dnspython`-backed.** Behavior should be
+  unchanged for existing callers when `dnspython` is installed (it's still
+  tried first), but a lookup that previously raised or returned `[]` because
+  `dnspython` failed for a reason unrelated to the DNS answer itself (e.g. a
+  malformed system resolver config) may now succeed via the `system` or
+  `nslookup` fallback instead.
+
+## [0.1.0] - 2026-07-25
+
+### Added
+
+- **Complete local-interface membership lookups.** `interfaces_for()` yields
+  every adapter matching an interface, exact address/`IPInterface`, network,
+  or `MACAddress`, while `interface_for()` keeps the first-match scalar
+  contract. `is_local_address()` distinguishes an assigned or loopback address
+  from one that is merely private, link-local, on-link or reachable.
+- **Static parser contracts.** `TypeForm` overloads preserve union and concrete
+  result types, callable builders, and explicit `try_parse(default=...)`
+  fallbacks. `IPInterfaceLike` now complements the existing input aliases.
+
+### Changed
+
+- `interface_for()` accepts networks and MAC addresses, including MAC text and
+  6-byte packed values. Integer MACs remain explicit `MACAddress` values. Its legacy
+  `strict=False` synthetic fallback remains address-only because a missing
+  network or MAC has no honest single-interface representation.
+- The IP input aliases now include packed bytes plus the exact stdlib
+  two-tuple and existing-interface forms accepted by the interface/network
+  factories. `is_valid()` is documented as a boolean convertibility check
+  rather than an unsound type guard for the original object.
+
 ## [0.0.2] - 2026-07-23
 
 ### Added
@@ -87,6 +155,8 @@ below is simply what the package contains.
 - **`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.1...HEAD
+[Unreleased]: https://github.com/jose-pr/netimps/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/netimps/compare/v0.0.2...v0.1.0
+[0.0.2]: https://github.com/jose-pr/netimps/releases/tag/v0.0.2
 [0.0.1]: https://github.com/jose-pr/netimps/releases/tag/v0.0.1
 [0.0.0]: https://github.com/jose-pr/netimps/releases/tag/v0.0.0

{netimps-0.0.2 → netimps-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netimps
-Version: 0.0.2
+Version: 0.2.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/
@@ -19,16 +19,19 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: System :: Networking
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
-Requires-Dist: dnspython
 Provides-Extra: cli
 Requires-Dist: duho>=0.3.3; extra == 'cli'
 Provides-Extra: dev
 Requires-Dist: black; extra == 'dev'
 Requires-Dist: build; extra == 'dev'
+Requires-Dist: dnspython; extra == 'dev'
 Requires-Dist: duho>=0.3.3; extra == 'dev'
 Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: mypy<2; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dns
+Requires-Dist: dnspython; extra == 'dns'
 Provides-Extra: docs
 Requires-Dist: mkdocs; extra == 'docs'
 Requires-Dist: mkdocs-material; extra == 'docs'
@@ -47,10 +50,13 @@ Description-Content-Type: text/markdown
 "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.
+Built on the standard library, with **no hard runtime dependencies**.
+`resolve()` tries `dnspython`, the OS resolver and `nslookup`, in that order,
+using whichever is available (`pip install netimps[dns]` for `dnspython`
+itself, the fullest of the three: structured records, every record type,
+explicit nameserver/search-list control). 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
 
@@ -58,13 +64,16 @@ and no wheel to miss for your platform.
   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.
+  `try_parse` and boolean `is_valid` siblings. Type-form overloads preserve the
+  parsed result, including v4/v6 union aliases and caller-supplied defaults.
 - **`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`.
+- **Local membership lookups** — `interface_for()` gives the first adapter for
+  an address, interface, network or MAC; `interfaces_for()` yields every match,
+  and `is_local_address()` distinguishes assignment from mere address scope.
 - **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
@@ -76,18 +85,20 @@ and no wheel to miss for your platform.
   `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.
+- **DNS and ping** — `resolve()` chaining `dnspython`/OS resolver/`nslookup`
+  backends and returning native types; `ping()` returning round-trip time and
+  TTL, not just a boolean.
 
 ## Installation
 
 ```bash
-pip install netimps          # the library
+pip install netimps          # the library -- no hard dependencies
+pip install netimps[dns]     # plus dnspython, for resolve()'s fullest backend
 pip install netimps[cli]     # plus the `netimps` command
 ```
 
-Requires Python 3.9+. The CLI extra adds `duho`; importing the library never
-requires it.
+Requires Python 3.9+. Both extras are additive and independent; importing the
+library never requires either.
 
 ## Command line
 
@@ -128,6 +139,11 @@ netimps.is_valid("::1", IPAddress)       # True
 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')
 
+# Exact assignment, subnet membership, or MAC ownership
+netimps.interface_for("192.0.2.10")      # first matching Interface, or None
+list(netimps.interfaces_for(parse("192.0.2.0/24", IPNetwork)))
+netimps.is_local_address("127.0.0.1")    # True without interface discovery
+
 # Honest reachability, and waiting for a service
 netimps.tcp_check("example.com", 443)              # True
 netimps.wait_for_port("localhost", 5432, timeout=60)
@@ -176,7 +192,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | Name | Purpose |
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
-| `IPAddressLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `IPAddressLike`, `IPInterfaceLike`, `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 |
@@ -187,7 +203,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | `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 |
+| `bind`, `bind_error_hint`, `interface_for`, `interfaces_for`, `is_local_address` | socket creation and local membership |
 | `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 |
@@ -212,6 +228,9 @@ A few behaviours are deliberate and worth knowing:
   `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.
+- **Addresses can belong to more than one interface.** `interface_for()` keeps
+  the historical first-match result; use `interfaces_for()` when duplicates
+  such as unscoped IPv6 link-local assignments matter.
 - **`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`

{netimps-0.0.2 → netimps-0.2.0}/README.md

@@ -10,10 +10,13 @@
 "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.
+Built on the standard library, with **no hard runtime dependencies**.
+`resolve()` tries `dnspython`, the OS resolver and `nslookup`, in that order,
+using whichever is available (`pip install netimps[dns]` for `dnspython`
+itself, the fullest of the three: structured records, every record type,
+explicit nameserver/search-list control). 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
 
@@ -21,13 +24,16 @@ and no wheel to miss for your platform.
   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.
+  `try_parse` and boolean `is_valid` siblings. Type-form overloads preserve the
+  parsed result, including v4/v6 union aliases and caller-supplied defaults.
 - **`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`.
+- **Local membership lookups** — `interface_for()` gives the first adapter for
+  an address, interface, network or MAC; `interfaces_for()` yields every match,
+  and `is_local_address()` distinguishes assignment from mere address scope.
 - **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
@@ -39,18 +45,20 @@ and no wheel to miss for your platform.
   `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.
+- **DNS and ping** — `resolve()` chaining `dnspython`/OS resolver/`nslookup`
+  backends and returning native types; `ping()` returning round-trip time and
+  TTL, not just a boolean.
 
 ## Installation
 
 ```bash
-pip install netimps          # the library
+pip install netimps          # the library -- no hard dependencies
+pip install netimps[dns]     # plus dnspython, for resolve()'s fullest backend
 pip install netimps[cli]     # plus the `netimps` command
 ```
 
-Requires Python 3.9+. The CLI extra adds `duho`; importing the library never
-requires it.
+Requires Python 3.9+. Both extras are additive and independent; importing the
+library never requires either.
 
 ## Command line
 
@@ -91,6 +99,11 @@ netimps.is_valid("::1", IPAddress)       # True
 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')
 
+# Exact assignment, subnet membership, or MAC ownership
+netimps.interface_for("192.0.2.10")      # first matching Interface, or None
+list(netimps.interfaces_for(parse("192.0.2.0/24", IPNetwork)))
+netimps.is_local_address("127.0.0.1")    # True without interface discovery
+
 # Honest reachability, and waiting for a service
 netimps.tcp_check("example.com", 443)              # True
 netimps.wait_for_port("localhost", 5432, timeout=60)
@@ -139,7 +152,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | Name | Purpose |
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
-| `IPAddressLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `IPAddressLike`, `IPInterfaceLike`, `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 |
@@ -150,7 +163,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | `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 |
+| `bind`, `bind_error_hint`, `interface_for`, `interfaces_for`, `is_local_address` | socket creation and local membership |
 | `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 |
@@ -175,6 +188,9 @@ A few behaviours are deliberate and worth knowing:
   `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.
+- **Addresses can belong to more than one interface.** `interface_for()` keeps
+  the historical first-match result; use `interfaces_for()` when duplicates
+  such as unscoped IPv6 link-local assignments matter.
 - **`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`

{netimps-0.0.2 → netimps-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netimps"
-version = "0.0.2"
+version = "0.2.0"
 authors = [{ name = "Jose A." }]
 description = "Small, self-contained network utilities: IP/MAC types, DNS lookup, ping, NIC discovery"
 readme = "README.md"
@@ -23,12 +23,16 @@ classifiers = [
     "Topic :: System :: Networking",
     "Typing :: Typed",
 ]
-dependencies = ["dnspython"]
+dependencies = []
 
 [project.optional-dependencies]
+# dnspython backs resolve_dnspython() only -- resolve_system()/resolve_nslookup()
+# (and resolve()'s fallback chain through them) work without it, so it is not a
+# hard dependency. Importing netimps must never require it.
+dns = ['dnspython']
 # The CLI is optional: importing netimps must never require duho.
 cli = ['duho>=0.3.3']
-dev = ['build', 'twine', 'hatchling', 'pytest', 'black', 'duho>=0.3.3']
+dev = ['build', 'twine', 'hatchling', 'pytest', 'black', 'mypy<2', 'duho>=0.3.3', 'dnspython']
 docs = ['mkdocs', 'mkdocs-material', 'mkdocstrings[python]']
 
 [project.scripts]
@@ -57,6 +61,10 @@ exclude = ["/.*"]
 # 3.9 is the floor, so don't let black emit syntax newer than that.
 target-version = ["py39"]
 
+[tool.mypy]
+python_version = "3.9"
+enable_incomplete_feature = ["TypeForm"]
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = ["tests"]

{netimps-0.0.2 → netimps-0.2.0}/src/netimps/AGENTS.md

@@ -16,7 +16,7 @@ is self-contained: it references nothing outside the installed distribution.
 testing, releasing) is not shipped; it lives with the source at
 <https://github.com/jose-pr/netimps>.
 
-`netimps.__version__` — the package version string (currently `"0.0.2"`).
+`netimps.__version__` — the package version string (currently `"0.2.0"`).
 
 ## Argument naming
 
@@ -27,7 +27,7 @@ The package is consistent about what the first argument means:
 | `dst` | where traffic is **sent** | `ping`, `tcp_check`, `wait_for_port`, `get_route`, `hop_count`, `discover_mtu` |
 | `src` | where traffic is **sent from** | `ping(src=)`, `get_free_port(src=)`, `discover_mtu(src=)` |
 | `host` / `network` | the thing being **examined** | `scan_ports(host)`, `scan_hosts(network)` |
-| `address` / `ip` | an address being **classified** (no DNS) | `get_ip`, `interface_for`, `is_multicast`, `is_link_scoped` |
+| `address` / `ip` | an address being **classified** (no DNS) | `get_ip`, `interface_for`, `interfaces_for`, `is_local_address`, `is_multicast`, `is_link_scoped` |
 
 `dst`/`src` are abbreviated symmetrically, matching packet-header convention.
 A `dst` accepts a hostname; an `address` does not.
@@ -55,6 +55,7 @@ The union aliases are **not callable** — `IPAddress("10.0.0.5")` is a
 | `IPInterface` | `IPv4Interface \| IPv6Interface` (address + prefix) |
 | `IPNetwork` | `IPv4Network \| IPv6Network` |
 | `IPAddressLike` | anything accepted *as input* for an address |
+| `IPInterfaceLike` | anything accepted *as input* for an address + prefix |
 | `IPNetworkLike` | anything accepted *as input* for a network |
 | `MACLike` | `str \| int \| bytes \| MACAddress` |
 
@@ -80,6 +81,9 @@ keyword. Key behaviours:
 - **Every type accepts the full stdlib input range** — `str`, `int`, packed
   `bytes`, or an existing object — because the builders are `ipaddress.ip_*`,
   not the concrete constructors.
+- **`IPInterface` and non-strict `IPNetwork` accept the stdlib two-tuple
+  form**, such as `("10.0.0.5", 24)`. `IPNetwork` also accepts an existing
+  `IPInterface` and normalises its host bits. `IPAddress` accepts neither.
 - **Unions accept either family; concrete types are strict.**
   `parse("::1", IPAddress)` works; `parse("::1", IPv4Address)` raises, because
   asking for v4 and receiving v6 would defeat the request.
@@ -91,6 +95,11 @@ keyword. Key behaviours:
   than being disguised as a rejected value.
 - An unusable `type` raises `TypeError` **even from `try_parse`** — a caller
   bug is not a rejected value.
+- Static type checkers preserve the selected result type, including the
+  `IPAddress`/`IPInterface`/`IPNetwork` unions, concrete classes, callable
+  builders, and the union with an explicit `try_parse(default=...)`.
+- **`is_valid` returns a plain `bool`; it does not narrow the original input.**
+  It proves convertibility, and parsing can create a different object.
 
 > **Gotcha:** `is_valid` uses an internal sentinel rather than testing
 > `try_parse(...) is not None`, so a builder that legitimately returns `None`
@@ -197,21 +206,97 @@ Where several schemes share a port the **canonical** one is returned (1080 →
 
 ## DNS
 
-**`resolve(query, rdtype="a", ns=None, timeout=5.0, port=53, tcp=False)`**
-
-Returns a `list`, **empty on any genuine lookup failure** (NXDOMAIN, no answer,
-all nameservers failed, timeout) — never `None`, so `if result:` and
-`result[0]` are safe.
-
-**Records are native types**: `A`/`AAAA` are `ipaddress` objects, everything
-else is `str` with the trailing root dot stripped and TXT strings unquoted.
-
-- **A malformed query or unknown record type raises `ValueError`** — a caller
-  bug, not a DNS result. A broad `except` here would make a typo'd record type
-  indistinguishable from "no such record".
+Three independently callable backends, plus `resolve()`, which chains them.
+All four share one contract: a `list`, **empty on any genuine lookup
+failure** (NXDOMAIN, NODATA, timeout) — never `None` — with **native
+types**: `A`/`AAAA` records are `ipaddress` objects, everything else is
+`str` (trailing root dot stripped, TXT strings unquoted).
+
+**`resolve(query, rdtype="a", ns=None, timeout=5.0, port=53, tcp=False, search=True, backends=None)`**
+
+Tries each backend in `backends` (default `["dnspython", "system",
+"nslookup"]`) until one gives a **definitive** answer — records, or a real
+empty result (NXDOMAIN/NODATA) — and returns that. A backend that could not
+even *attempt* the query (missing binary, `dnspython` not installed, a
+`rdtype`/`ns` it structurally can't serve) is skipped or falls through,
+never mistaken for "no records". If every applicable backend fails that way,
+the last such error is raised. `backends` also accepts a single name as a
+plain string (`backends="system"`), or a custom order/subset
+(`backends=["nslookup", "dnspython"]`).
+
+- **`system`** is skipped automatically for a non-address `rdtype` or an
+  explicit `ns=`/`port=` — it has no per-call nameserver override, so running
+  it anyway would silently ignore the caller's choice.
+- A malformed query or unknown record type raises `ValueError` immediately,
+  without trying every backend — that's a caller bug, not a resolution
+  outcome.
+
+**`resolve_dnspython(query, rdtype="a", ns=None, timeout=5.0, port=53, tcp=False, search=True)`**
+
+The original backend: `dnspython`, structured records, every `rdtype`.
+
+- **`ns=None` (default) uses the system resolver configuration** —
+  `/etc/resolv.conf` on POSIX, the registry on Windows. Pass `ns=` (a string
+  or list) to query specific nameservers instead; a malformed `ns=` raises
+  immediately, before any query is attempted.
+- **`search=True` (default) tries the resolver's search list** (the
+  `search`/`domain` directive in `resolv.conf`, or the Windows per-adapter DNS
+  suffix list) for an unqualified `query` — e.g. `resolve_dnspython("db1")`
+  trying `db1.internal.example.com`, the same as `ping db1` would.
+  `search=False` looks up `query` literally. A **list of domain names**
+  (`search=["eng.example.com", "example.com"]`) tries exactly those suffixes
+  instead of the system list, regardless of `ns`. Ignored for an
+  already-qualified (trailing-dot) `query`.
 - `timeout` bounds the **whole resolution including retries**, so a list of
   dead nameservers cannot run past it.
-- Requires `dnspython` — the package's only runtime dependency.
+- Requires `dnspython` — the package's only runtime dependency. Raises
+  `ResolutionError` (not `ValueError`) if it isn't installed, so `resolve()`'s
+  chain falls through to the next backend instead of erroring outright.
+
+**`resolve_system(query, rdtype="a", timeout=5.0, search=True)`**
+
+The OS resolver, via `socket.getaddrinfo()` — **hosts file, NSS
+(`nsswitch.conf`) and DNS, in the order the OS applies them**, including any
+OS-level resolver cache. This is what `resolve_dnspython` cannot see (its own
+DNS query bypasses all of that).
+
+- **Address records only**: `rdtype` must be `"a"` or `"aaaa"`; anything else
+  raises `ResolutionError` immediately, no query attempted.
+- **No `ns=` override** — `getaddrinfo` always asks whatever resolver the OS
+  is configured with; there's no per-call nameserver parameter at that layer
+  (not even via `ctypes` — reaching a specific nameserver without shelling
+  out means speaking DNS wire protocol yourself, which is what `dnspython`
+  already does).
+- **`search`**: `getaddrinfo` itself takes no search-list parameter either, so
+  `search=True` (default) just leaves `query` as given and the OS resolver's
+  own configured search list (glibc `ndots`/`search`, Windows per-adapter DNS
+  suffix) applies as it normally would. `search=False` appends a trailing
+  `.`, which every resolver reads as "already fully qualified" — the same
+  trick `host`/`getent` scripts use. A **list of domain names** tries `query`
+  qualified with each, in order, one `getaddrinfo` call per candidate,
+  independent of (and untouched by) the OS's own search list.
+
+**`resolve_nslookup(query, rdtype="a", ns=None, timeout=5.0, search=True)`**
+
+Shells out to the `nslookup` binary — a fallback for when neither Python-level
+path is usable. Address records only: `rdtype` must be `"a"`, `"aaaa"` or
+`"ptr"`.
+
+- Parses **both BIND-style** (`Address: 1.2.3.4`, one line per address) **and
+  Windows-style** (`Addresses:` with continuation lines, and NODATA as a bare
+  `Name:` line with no address and no error text) output. Windows also prints
+  its NXDOMAIN message on **stderr**, not stdout — both streams are checked.
+- `ns=` is passed as `nslookup`'s trailing `server` argument (a single
+  nameserver, not a list).
+- **`search`** has the same three-way contract as the other backends, but
+  `nslookup` has no built-in search-list handling — this issues one
+  `nslookup` call per candidate name, in order, stopping at the first with
+  actual records. `search=True` (default) draws the candidate list from the
+  system resolver's search config (reusing `dnspython`'s `resolv.conf`/
+  registry parsing if it's installed; `[]` — literal name only — if not).
+- Raises `ResolutionError` (not `ValueError`) for a missing binary, a
+  timeout, or an unparseable output shape — a genuine "no such name" is
+  still `[]`.
 
 ## Reachability
 
@@ -257,9 +342,26 @@ failure. `tcp` and `udp` also report `rtt_ms`; only ICMP reports `ttl`.
   for a bind failure, recognising POSIX errnos *and* Windows `10013`/`10048`.
   Returns `None` for anything unrecognised, so the caller keeps the original
   error. **Does not raise** — what to do with a failure is the caller's call.
-- **`interface_for(address, strict=True) -> Interface | None`** — reverse
-  lookup. `strict=False` synthesizes a host-route interface named
-  `"<unknown>"` instead of returning `None`.
+- **`interface_for(query, strict=True) -> Interface | None`** — first matching
+  adapter in OS enumeration order. `query` accepts an `Interface`, exact
+  `IPAddress`, exact `.ip` from an `IPInterface`, an `IPNetwork` containing at
+  least one assigned address, or an exact `MACAddress`. Address-like strings,
+  integers and packed bytes remain accepted; a slash-bearing string is a
+  network. MAC text and 6-byte packed values are recognised after IP parsing.
+  Integer MACs must be wrapped in `MACAddress` because integers are also valid
+  IP-address inputs. Invalid input and misses return `None`. With
+  `strict=False`, only an address or `IPInterface` miss synthesizes a host-route
+  interface named `"<unknown>"`; networks and MACs have no honest synthetic
+  result.
+- **`interfaces_for(query) -> Iterator[Interface]`** — every match for the same
+  query forms, in OS order and with each adapter yielded once even if several
+  assigned addresses match. An `Interface` yields itself without enumeration.
+  Addresses need not be unique across adapters (unscoped IPv6 link-local is a
+  common example), so use this plural form when every owner matters.
+- **`is_local_address(address) -> bool`** — true only for loopback or an
+  address assigned to a local adapter. Private, link-local, on-link, routable
+  or reachable alone do not count. Malformed input raises like `parse`;
+  loopback answers before interface discovery.
 - **`get_source_ip(dst="8.8.8.8", port=80)`** — which local address the kernel
   would use to reach `dst`. **Sends no packets.** The answer depends on
   `dst`: with a VPN up, a public probe returns the tunnel address and a LAN