netimps 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -62,19 +62,22 @@ Requires Python 3.9+. No hard runtime dependencies.
 
 ```
 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
-├── cli.py        # public: duho-backed CLI (needs the `cli` extra)
-├── __main__.py   # `python -m netimps`
-├── _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() chaining dnspython/system/nslookup backends
-├── _ping.py      # private: ping() over the platform binary
-└── py.typed      # PEP 561 marker — the package ships inline type hints
+├── __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
+├── cli.py         # public: duho-backed CLI (needs the `cli` extra)
+├── __main__.py    # `python -m netimps`
+├── _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() chaining dnspython/system/nslookup backends
+├── _ping.py       # private: ping() over the platform binary
+├── _retry.py      # private: bounded retry with exponential backoff
+├── _udp.py        # private: UDP receive with arrival interface (IP_PKTINFO)
+├── _iface_spec.py # private: shared InterfaceSpec coercion (MAC/name/Interface -> address)
+└── py.typed       # PEP 561 marker — the package ships inline type hints
 ```
 
 **The import surface is still flat** — everything is re-exported from
@@ -96,6 +99,7 @@ map:
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
 | `IPAddressLike`, `IPInterfaceLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `AddressLike` | accepted-input union for a single destination (hostname, address, or interface object) |
 | `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 |
@@ -104,7 +108,7 @@ map:
 | `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) |
+| `resolve`, `resolve_dnspython`, `resolve_system`, `resolve_nslookup` | DNS lookup → native records (`[]` on failure); `resolve` chains the three backends, each independently callable |
 | `ping`, `PingResult` | reachability with RTT and TTL |
 | `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 |
@@ -144,6 +148,23 @@ map:
 - **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.
+- **IPv6 multicast names an adapter by *index*, IPv4 by *address*.** They are
+  not two spellings of one thing: feeding an address to the v6 side does not
+  raise, it lands as index `0`, which is "kernel's choice". Use
+  `_iface_spec.interface_index()` for anything v6, `interface_address()` for
+  v4.
+- **POSIX delivers asynchronous ICMP errors only to *connected* UDP sockets.**
+  An unconnected probe never sees a port-unreachable and just times out, while
+  Windows reports it either way — so the unconnected version tests green here
+  and under-reports on Linux CI. Also note `_discover_mtu_udp` is still
+  unconnected by design; it treats such errors as failure anyway.
+- **`ThreadPoolExecutor.__exit__` calls `shutdown(wait=True)`,** and its atexit
+  hook joins worker threads too. It is therefore the wrong tool for bounding a
+  blocking call: a daemon `threading.Thread` joined through a queue is what
+  `_dns._resolve_system_once` uses, and why.
+- **Match a ping reply by address token, and remember hostnames are plural.**
+  `gethostbyname` is IPv4-only — use `getaddrinfo` with an explicit family, or
+  `ipv6=` silently does nothing.
 - **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;

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

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.2] - 2026-08-16
+
+### Fixed
+
+- **`resolve_system(timeout=)` now bounds wall time.** The lookup ran inside a
+  `with ThreadPoolExecutor(...)` block, whose `__exit__` joins the worker
+  still blocked in `getaddrinfo` -- so the timeout changed *what* was raised
+  but not *when*, and a 30s resolver hang still cost the caller 30s despite
+  `timeout=5.0`. `resolve()`'s chain consequently never reached `nslookup` at
+  the promised deadline either.
+- **`interface=` is honoured for IPv6 multicast.** The spec was reduced to an
+  address and then passed to `if_nametoindex()`, which always fails for an
+  address string, so the `IPV6_JOIN_GROUP` index silently stayed `0` --
+  "kernel's choice", the exact default `interface=` exists to override.
+  `IPV6_MULTICAST_IF` was never set at all, so sends left by the default
+  route while joins listened elsewhere. Both now resolve the adapter to its
+  interface index. IPv4 behaviour is unchanged.
+- **`ping(hostname, ipv6=True)` is no longer always false.** The reply address
+  was resolved with the IPv4-only `gethostbyname`, so a v6 reply was checked
+  against a v4 expectation and never matched. The expectation now comes from
+  `getaddrinfo` honouring `ipv6=`, and a name resolving to several addresses
+  counts as answered if the reply came from any of them.
+- **`ping(..., method="tcp"/"udp")` reaches IPv6 destinations.** Both probes
+  opened `AF_INET` sockets unconditionally, so a v6 destination failed inside
+  `connect`/`sendto` and was reported as unreachable -- a wrong falsy answer
+  rather than an error. `ipv6=` now applies to all three methods.
+- **`ping(..., method="udp")` detects ICMP port-unreachable on POSIX.** The
+  probe socket was never connected, and POSIX delivers asynchronous ICMP
+  errors only to connected UDP sockets -- so the documented "host answered,
+  nothing listening" signal worked on Windows alone and the probe just timed
+  out on Linux/macOS. `ECONNREFUSED` and `ECONNRESET` both now count.
+
+### Documentation
+
+- The shipped API header named `PingResult.source` and `Route.source`; both
+  attributes are spelled `.src` (and `PingResult.host` was unlisted).
+- Recorded the per-family multicast interface selection, `ping`'s `ipv6=`
+  reach across all three methods, and `resolve_system`'s real wall-time
+  deadline in the shipped header.
+- Added the known, still-unverified macOS/BSD `ping6` reply-shape gap
+  (`from <addr>,` rather than `from <addr>:`) to the header rather than
+  guessing a parser change without a macOS runner.
+
+## [0.2.1] - 2026-07-30
+
+### Added
+
+- **`AddressLike`**, a new type alias (`str | IPv4Address | IPv6Address |
+  IPv4Interface | IPv6Interface`) accepted by every `dst`-typed parameter:
+  `ping`, `tcp_check`, `wait_for_port`, `get_route`, `hop_count`, `get_pmtu`,
+  `discover_mtu`, `get_tcp_mss`, `scan_ports(host)`, `get_ip`,
+  `UdpEndpoint.send`, and `resolve`'s (and its backends') `query`. An
+  `IPv4Interface`/`IPv6Interface` unwraps to its `.ip` -- previously passing
+  one stringified with its `/prefix` intact, which every consumer
+  (subprocess argument, socket call, DNS query) read as garbage. A network
+  (`IPv4Network`/`IPv6Network`) raises `TypeError`, since it has no single
+  address to use.
+- **`resolve()` (and all three backends) auto-select `rdtype`.** It now
+  defaults to `None`, which picks `"ptr"` when `query` is an address literal
+  and `"a"` otherwise -- `resolve("8.8.8.8")` now returns `['dns.google']`
+  instead of attempting a nonsensical A lookup on a literal address. Pass an
+  explicit `rdtype` to opt out. `resolve_system()` gains `"ptr"` support (via
+  `socket.gethostbyaddr()`) to make this work across every backend.
+
+### Fixed
+
+- **`ping(src=...)` crashed with `NameError` instead of returning a falsy
+  result** when `src` named an interface with no usable address (e.g. an
+  unknown adapter name, or a MAC not currently present) -- a leftover
+  reference to an undefined `hostname` variable instead of `dst`. Found via
+  a `mypy` pass while auditing type annotations; a regression test now
+  covers the path.
+
+### Changed
+
+- Public functions across the package now carry complete parameter and
+  return type annotations (previously missing on, among others, `collapse`,
+  `subtract`, `get_ip`, `PingResult`, `Route`, `scan_hosts`, `is_multicast`,
+  `join_group`/`leave_group`, `multicast_socket`, `UdpEndpoint`, and `bind`).
+  The recurring "loose interface spec" parameter (`ping(src=)`,
+  `bind(interface=)`, `discover_mtu(src=)`, `multicast_socket(interface=)`,
+  etc.) now shares one internal type alias instead of being unannotated at
+  each call site.
+
 ## [0.2.0] - 2026-07-29
 
 ### Added
@@ -155,7 +239,10 @@ 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.1.0...HEAD
+[Unreleased]: https://github.com/jose-pr/netimps/compare/v0.2.2...HEAD
+[0.2.2]: https://github.com/jose-pr/netimps/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/jose-pr/netimps/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/jose-pr/netimps/compare/v0.1.0...v0.2.0
 [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

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: netimps
-Version: 0.2.0
+Version: 0.2.2
 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/
@@ -16,6 +16,7 @@ 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: Programming Language :: Python :: 3.14
 Classifier: Topic :: System :: Networking
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
@@ -86,8 +87,9 @@ nothing to compile and no wheel to miss for your platform.
 - **Multicast** — `multicast_socket` handling the join dance whose failure
   modes are otherwise silent.
 - **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.
+  backends and returning native types, accepting an IP/interface object
+  directly and auto-selecting a reverse lookup for an address query; `ping()`
+  returning round-trip time and TTL, not just a boolean.
 
 ## Installation
 
@@ -106,6 +108,7 @@ library never requires either.
 netimps interfaces                       # names, MACs, MTU, addresses
 netimps ping 8.8.8.8 -m tcp -p 443       # icmp | tcp | udp
 netimps resolve example.com aaaa
+netimps resolve 8.8.8.8                  # no rdtype -> auto ptr -> dns.google
 netimps check example.com https          # port number or scheme name
 netimps mtu 8.8.8.8                      # measured, not guessed
 netimps scan 192.0.2.0/29 -p common
@@ -193,6 +196,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
 | `IPAddressLike`, `IPInterfaceLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `AddressLike` | accepted-input union for a single destination (hostname, address, or `IPv4Interface`/`IPv6Interface` — its `.ip` is used) |
 | `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 |

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

@@ -46,8 +46,9 @@ nothing to compile and no wheel to miss for your platform.
 - **Multicast** — `multicast_socket` handling the join dance whose failure
   modes are otherwise silent.
 - **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.
+  backends and returning native types, accepting an IP/interface object
+  directly and auto-selecting a reverse lookup for an address query; `ping()`
+  returning round-trip time and TTL, not just a boolean.
 
 ## Installation
 
@@ -66,6 +67,7 @@ library never requires either.
 netimps interfaces                       # names, MACs, MTU, addresses
 netimps ping 8.8.8.8 -m tcp -p 443       # icmp | tcp | udp
 netimps resolve example.com aaaa
+netimps resolve 8.8.8.8                  # no rdtype -> auto ptr -> dns.google
 netimps check example.com https          # port number or scheme name
 netimps mtu 8.8.8.8                      # measured, not guessed
 netimps scan 192.0.2.0/29 -p common
@@ -153,6 +155,7 @@ netimps.retry(lambda: netimps.tcp_check("example.com", 443), attempts=3)
 | --- | --- |
 | `IPAddress`, `IPInterface`, `IPNetwork` | v4/v6 **union aliases** for annotations |
 | `IPAddressLike`, `IPInterfaceLike`, `IPNetworkLike`, `MACLike` | accepted-input unions |
+| `AddressLike` | accepted-input union for a single destination (hostname, address, or `IPv4Interface`/`IPv6Interface` — its `.ip` is used) |
 | `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 |

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netimps"
-version = "0.2.0"
+version = "0.2.2"
 authors = [{ name = "Jose A." }]
 description = "Small, self-contained network utilities: IP/MAC types, DNS lookup, ping, NIC discovery"
 readme = "README.md"
@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: OS Independent",
     "Topic :: System :: Networking",
     "Typing :: Typed",

{netimps-0.2.0 → netimps-0.2.2}/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.2.0"`).
+`netimps.__version__` — the package version string (currently `"0.2.2"`).
 
 ## Argument naming
 
@@ -24,7 +24,7 @@ The package is consistent about what the first argument means:
 
 | Name | Meaning | Examples |
 | --- | --- | --- |
-| `dst` | where traffic is **sent** | `ping`, `tcp_check`, `wait_for_port`, `get_route`, `hop_count`, `discover_mtu` |
+| `dst` | where traffic is **sent** | `ping`, `tcp_check`, `wait_for_port`, `get_route`, `hop_count`, `discover_mtu`, `get_tcp_mss`, `get_pmtu`, `scan_ports(host)` |
 | `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`, `interfaces_for`, `is_local_address`, `is_multicast`, `is_link_scoped` |
@@ -32,6 +32,14 @@ The package is consistent about what the first argument means:
 `dst`/`src` are abbreviated symmetrically, matching packet-header convention.
 A `dst` accepts a hostname; an `address` does not.
 
+**Every `dst`-typed parameter accepts `AddressLike`** — a hostname string, an
+address string, an existing `IPv4Address`/`IPv6Address`, or an
+`IPv4Interface`/`IPv6Interface` (its `.ip` is used, dropping the `/prefix`,
+which every consumer of a destination -- a subprocess argument, a socket
+call, a DNS query -- would otherwise read as garbage). A network
+(`IPv4Network`/`IPv6Network`) raises `TypeError`, since it has no single
+address to send to. `get_ip` and `resolve`'s `query` accept the same forms.
+
 ## Types vs parsing — read this first
 
 The noun names are **types you annotate with**; you turn values into them with
@@ -57,6 +65,7 @@ The union aliases are **not callable** — `IPAddress("10.0.0.5")` is a
 | `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 |
+| `AddressLike` | `str \| IPv4Address \| IPv6Address \| IPv4Interface \| IPv6Interface` -- any `dst`-typed parameter |
 | `MACLike` | `str \| int \| bytes \| MACAddress` |
 
 Plus the stdlib concretes re-exported so callers need not import `ipaddress`:
@@ -212,7 +221,22 @@ 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)`**
+**`resolve(query, rdtype=None, ns=None, timeout=5.0, port=53, tcp=False, search=True, backends=None)`**
+
+`query` accepts `AddressLike` (a hostname string, an address string, an
+`IPv4Address`/`IPv6Address`, or an `IPv4Interface`/`IPv6Interface` -- its
+`.ip` is used), not just a plain string.
+
+`rdtype=None` (default) **auto-selects**: `"ptr"` when `query` is an address
+literal (an `"a"`/`"aaaa"` lookup *of* an address makes no sense), `"a"`
+otherwise -- the same default as before this was configurable::
+
+    resolve("example.com")   # rdtype auto -> "a"  -> ['93.184.216.34']
+    resolve("8.8.8.8")       # rdtype auto -> "ptr" -> ['dns.google']
+
+Pass an explicit `rdtype` to opt out -- `rdtype="a"` on an address still
+attempts a literal (and empty) A lookup rather than being silently
+overridden.
 
 Tries each backend in `backends` (default `["dnspython", "system",
 "nslookup"]`) until one gives a **definitive** answer — records, or a real
@@ -224,16 +248,21 @@ 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.
+- **`system`** is skipped automatically for a `rdtype` outside
+  `"a"`/`"aaaa"`/`"ptr"`, 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)`**
+**`resolve_dnspython(query, rdtype=None, ns=None, timeout=5.0, port=53, tcp=False, search=True)`**
 
-The original backend: `dnspython`, structured records, every `rdtype`.
+The original backend: `dnspython`, structured records, every `rdtype`. Same
+`AddressLike` `query` and auto-`rdtype` behavior as `resolve()`. A `"ptr"`
+lookup (explicit or auto-selected) uses dnspython's `resolve_address()`,
+which builds the reverse (`in-addr.arpa`/`ip6.arpa`) name from the literal
+address itself -- the caller never constructs that name by hand.
 
 - **`ns=None` (default) uses the system resolver configuration** —
   `/etc/resolv.conf` on POSIX, the registry on Windows. Pass `ns=` (a string
@@ -249,25 +278,30 @@ The original backend: `dnspython`, structured records, every `rdtype`.
   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. 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
+- `dnspython` is an **optional** dependency (`pip install netimps[dns]`).
+  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=None, timeout=5.0, search=True)`**
+
+The OS resolver, via `socket.getaddrinfo()`/`socket.gethostbyaddr()` — **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). Same `AddressLike`
+`query` and auto-`rdtype` behavior as `resolve()`.
+
+- **Address and reverse records only**: `rdtype` must be `"a"`, `"aaaa"` or
+  `"ptr"`; anything else raises `ResolutionError` immediately, no query
+  attempted. `"ptr"` goes through `gethostbyaddr()` rather than
+  `getaddrinfo()` and returns `[hostname]`.
+- **No `ns=` override** — the OS resolver functions always ask whatever
+  nameserver the OS is configured with; there's no per-call 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`** (ignored for `"ptr"`, which has no suffix to expand):
+  `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
@@ -275,12 +309,18 @@ DNS query bypasses all of that).
   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.
+- **`timeout` bounds wall time, per candidate name tried.** `getaddrinfo` has
+  no timeout of its own, so each attempt runs in a daemon helper thread that
+  is abandoned at the deadline; the underlying call is not cancelled, but
+  neither the caller nor interpreter exit waits for it. A broken resolver
+  therefore costs `timeout`, not however long it takes to give up — which is
+  also what lets `resolve()`'s chain reach `nslookup` on schedule.
 
-**`resolve_nslookup(query, rdtype="a", ns=None, timeout=5.0, search=True)`**
+**`resolve_nslookup(query, rdtype=None, 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"`.
+`"ptr"`. Same `AddressLike` `query` and auto-`rdtype` behavior as `resolve()`.
 
 - 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
@@ -288,12 +328,13 @@ path is usable. Address records only: `rdtype` must be `"a"`, `"aaaa"` or
   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).
+- **`search`** has the same three-way contract as the other backends
+  (ignored for `"ptr"`), 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 `[]`.
@@ -303,11 +344,12 @@ path is usable. Address records only: `rdtype` must be `"a"`, `"aaaa"` or
 **`ping(dst, tries=1, timeout=1.0, ipv6=None, src=None, size=None, ttl=None, dont_fragment=False, method="icmp", port=None) -> PingResult`**
 
 `PingResult` is **truthy on success** and compares equal to `bool`, so
-`if ping(host):` and `== True` keep working, while carrying `.ok`, `.rtt_ms`,
-`.ttl`, `.source`, `.attempts`.
+`if ping(host):` and `== True` keep working, while carrying `.ok`, `.host`,
+`.rtt_ms`, `.ttl`, `.src`, `.attempts`.
 
 | Argument | Notes |
 | --- | --- |
+| `dst` | `AddressLike` (hostname, address string, address object, or `IPv4Interface`/`IPv6Interface` -- its `.ip` is pinged). `ping(get_interfaces()[0].ipv4[0])` works directly. |
 | `src` | `Interface`, address, **MAC**, adapter name or string. A MAC is resolved to the adapter holding it. |
 | `size` | ICMP payload bytes. The wire packet is **28 bytes larger** (20 IP + 8 ICMP). |
 | `ttl` | initial hop limit — `-i` on Windows, `-t` on POSIX (the letters are **swapped**). |
@@ -324,6 +366,19 @@ failure. `tcp` and `udp` also report `rtt_ms`; only ICMP reports `ttl`.
   "TTL expired in transit", so the reply address is verified rather than
   trusting the exit code. Locale-independent — it matches on addresses, never
   prose.
+- **`ipv6=` applies to all three methods**, not just the ICMP binary: it picks
+  the `-6`/`-4` flag, the family the reply address is resolved in, and the
+  family the `tcp`/`udp` probe sockets use. `ipv6=None` accepts either. A
+  hostname with several addresses counts as answered if the reply came from
+  any of them.
+- **The `udp` probe connects its socket before sending**, which is why the ICMP
+  port-unreachable is seen on POSIX and not only on Windows — an unconnected
+  UDP socket is never delivered an asynchronous ICMP error on Linux/BSD.
+  `ECONNREFUSED` and `ECONNRESET` both count as "the host answered".
+- **Known gap: macOS/BSD `ping6` reply lines.** Verification looks for
+  `from <addr>:`; BSD `ping6` is documented as printing `from <addr>,`. If
+  that holds, a v6 *literal* ping on macOS verifies as falsy despite a healthy
+  reply. Unverified on real hardware, so deliberately not "fixed" by guess.
 - An unusable `src` (unknown MAC, adapter with no address, foreign address)
   gives a falsy result — it **never silently falls back** to the default route.
 - Never raises: missing binary, hung subprocess and non-zero exit are all falsy.
@@ -363,9 +418,11 @@ failure. `tcp` and `udp` also report `rtt_ms`; only ICMP reports `ttl`.
   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
-  probe the physical one. Correct where hostname resolution picks a VM adapter.
+  would use to reach `dst`. `dst` accepts `AddressLike` (an address object or
+  `IPv4Interface`/`IPv6Interface`, not just a string). **Sends no packets.**
+  The answer depends on `dst`: with a VPN up, a public probe returns the
+  tunnel address and a LAN probe the physical one. Correct where hostname
+  resolution picks a VM adapter.
 - **`get_free_port(src="127.0.0.1", family=AF_INET) -> int`** — bind port 0 and
   read it back. **Inherently racy** — the port frees the instant it returns; if
   you can, bind port 0 in the server itself instead. `SO_REUSEADDR` is
@@ -379,7 +436,7 @@ failure. `tcp` and `udp` also report `rtt_ms`; only ICMP reports `ttl`.
 
 ## Routing, hops and MTU
 
-- **`get_route(dst="8.8.8.8") -> Route`** — `.source`, `.gateway`,
+- **`get_route(dst="8.8.8.8") -> Route`** — `.dst`, `.src`, `.gateway`,
   `.interface_index`, `.on_link`. **First hop only, deliberately** — that is
   available unprivileged everywhere, unlike the full path. Never raises;
   unknown pieces are `None`/`0`. The gateway resolves on Windows and Linux only.
@@ -463,6 +520,12 @@ receives nothing, and looks fine:
   *both* send and receive. Without it the kernel picks by routing table, which
   on a multi-homed host is regularly the wrong adapter. An unknown interface
   **raises** rather than falling back.
+- **The two families identify an adapter differently**, and the spec is
+  resolved accordingly: IPv4 by local *address* (`IP_ADD_MEMBERSHIP`,
+  `IP_MULTICAST_IF`), IPv6 by interface *index* (`IPV6_JOIN_GROUP`,
+  `IPV6_MULTICAST_IF`). An adapter the platform reports **no index** for
+  raises for an IPv6 group, because index `0` means "kernel's choice" — the
+  default `interface=` was passed to override.
 
 ## UDP with arrival interface
 
@@ -473,7 +536,9 @@ network a request came from.
 
 `recv(bufsize, resolve_interface=True) -> Datagram`, with `.data`, `.sender`,
 `.local_address`, `.interface_index` and `.interface`.
-`send(data, address, port, source=None)` pins the outgoing interface.
+`send(data, address, port, src=None)` pins the outgoing interface. `address`
+accepts `AddressLike`; `src` the usual loose interface spec (`Interface`,
+MAC, adapter name or address).
 
 - **Degrades rather than failing.** `recvmsg` does not exist on Windows and
   `IP_PKTINFO` is not universal; there the interface fields are simply empty.
@@ -526,6 +591,7 @@ dependency on the CLI half.
 netimps interfaces                       # names, MACs, MTU, addresses
 netimps ping 8.8.8.8 -m tcp -p 443       # icmp | tcp | udp
 netimps resolve example.com aaaa
+netimps resolve 8.8.8.8                  # no rdtype -> auto ptr -> dns.google
 netimps check example.com https          # port or scheme name
 netimps route 8.8.8.8 --hops
 netimps mtu 8.8.8.8 -m udp -p 9999

{netimps-0.2.0 → netimps-0.2.2}/src/netimps/__init__.py

@@ -74,6 +74,7 @@ from ._ip import (
     _BUILDERS,
     _BUILDER_DEFAULTS,
     _CONCRETE,
+    AddressLike,
     IPAddress,
     IPAddressLike,
     IPInterface,
@@ -102,6 +103,7 @@ __all__ = [
     "IPAddressLike",
     "IPInterfaceLike",
     "IPNetworkLike",
+    "AddressLike",
     "MACLike",
     # Parsing.
     "parse",
@@ -161,7 +163,7 @@ __all__ = [
     "HOST_DN",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"
 
 #: Fully-qualified (or short) name of the host running this process.
 HOST_DN = _platform.node()