ipscout 2.0.0__tar.gz → 2.1.0__tar.gz

{ipscout-2.0.0 → ipscout-2.1.0}/CHANGELOG.md

@@ -5,6 +5,32 @@ the [Keep a Changelog](https://keepachangelog.com/) format.
 
 ## [Unreleased]
 
+## [2.1.0] 2026-10-24 17:18:42
+
+### Added
+
+- `grab_banners` / `agrab_banners`: read the first line each of many hosts sends on one TCP port,
+  connecting, reading, optionally sending a `farewell` such as `b"QUIT\r\n"`, and closing on ONE
+  connection per host, so a device that refuses a second connect right after a session is still
+  read. Each host gets a `Banner` whose `BannerState` is `GREETED` (with `line`), `SILENT`,
+  `REFUSED` or `UNREACHABLE` (with `error`); a name that does not resolve is a result, not an
+  exception. One `timeout` per host covers resolution, connect and read; results keep input order.
+- `ipscout banners HOSTS... --port N`, the 22nd subcommand. A `HOSTS` item written as a network
+  expands to its hosts within the sweep bound; `--farewell` decodes `\r`, `\n`, `\t` and `\\`.
+  Exits 1 when no host greeted.
+
+### Fixed
+
+- `ping_many` / `aping_many` return their mapping in the order the targets were given, as documented.
+  It was in completion order, so a target that timed out ahead of one that answered came after it.
+- The TCP fallback (`allow_tcp_fallback`, `is_reachable`) counts a refused connection as an answer
+  in every spelling a platform uses for it. It recognised only `ConnectionRefusedError`, so a refusal
+  arriving as a bare `OSError` with `ECONNREFUSED`, or with the Windows numbering 10061 / 1225,
+  reported a live host as unanswered.
+- In `--json` and `--json-bare` modes, an invalid option value is reported with the option's name
+  (`Invalid value for '--timeout': ...`). The JSON error message carried only Click's bare text,
+  which did not say which option was wrong.
+
 ## [2.0.0] 2026-10-24 12:32:19
 
 ### Changed

{ipscout-2.0.0 → ipscout-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ipscout
-Version: 2.0.0
+Version: 2.1.0
 Summary: Ping, traceroute and local-network inspection in pure Python - no subprocess, and no admin rights on the default paths
 Project-URL: Homepage, https://github.com/bitranox/ipscout
 Project-URL: Repository, https://github.com/bitranox/ipscout.git
@@ -29,7 +29,7 @@ Requires-Dist: rtoml>=0.14.0
 Provides-Extra: dev
 Requires-Dist: bandit>=1.9.4; extra == 'dev'
 Requires-Dist: build>=1.6.1; extra == 'dev'
-Requires-Dist: certifi>=2026.10.19; extra == 'dev'
+Requires-Dist: certifi>=2026.10.23; extra == 'dev'
 Requires-Dist: click>=8.5.0; extra == 'dev'
 Requires-Dist: hatchling>=1.32.4; extra == 'dev'
 Requires-Dist: import-linter>=2.15; extra == 'dev'
@@ -201,6 +201,7 @@ ipscout ping-many 127.0.0.1 ::1 -c 1
 ipscout reachable example.com
 ipscout traceroute 1.1.1.1 --max-hops 10
 ipscout scan-ports 192.168.1.10 --ports 22,80,443,8000-8100
+ipscout banners 192.0.2.0/24 --port 21 --farewell 'QUIT\r\n'   # what each host says first
 ipscout mac 8.8.8.8                     # the gateway's, labelled NEXT_HOP
 ipscout find-ip dc:b2:2f:44:34:59 --scan
 ipscout arp-scan --network 192.168.1.0/24
@@ -234,6 +235,7 @@ ipscout.sweep_scope()  # what a default sweep covers, and what is too wide for i
 ipscout.default_gateway()  # and query_route() for any destination
 ipscout.subnet_info()  # addressing, gateway, stored DHCP facts
 ipscout.scan_ports(host, "22,80,8000-8100")
+ipscout.grab_banners(hosts, 21, farewell=b"QUIT\r\n")  # each host's first line, on one connection
 ipscout.path_mtu("8.8.8.8")
 ipscout.wake_on_lan(mac, broadcast="192.168.1.255")
 ipscout.observe_dhcp(mac, interface="br0")  # a machine that has no address yet (needs elevation)

{ipscout-2.0.0 → ipscout-2.1.0}/README.md

@@ -155,6 +155,7 @@ ipscout ping-many 127.0.0.1 ::1 -c 1
 ipscout reachable example.com
 ipscout traceroute 1.1.1.1 --max-hops 10
 ipscout scan-ports 192.168.1.10 --ports 22,80,443,8000-8100
+ipscout banners 192.0.2.0/24 --port 21 --farewell 'QUIT\r\n'   # what each host says first
 ipscout mac 8.8.8.8                     # the gateway's, labelled NEXT_HOP
 ipscout find-ip dc:b2:2f:44:34:59 --scan
 ipscout arp-scan --network 192.168.1.0/24
@@ -188,6 +189,7 @@ ipscout.sweep_scope()  # what a default sweep covers, and what is too wide for i
 ipscout.default_gateway()  # and query_route() for any destination
 ipscout.subnet_info()  # addressing, gateway, stored DHCP facts
 ipscout.scan_ports(host, "22,80,8000-8100")
+ipscout.grab_banners(hosts, 21, farewell=b"QUIT\r\n")  # each host's first line, on one connection
 ipscout.path_mtu("8.8.8.8")
 ipscout.wake_on_lan(mac, broadcast="192.168.1.255")
 ipscout.observe_dhcp(mac, interface="br0")  # a machine that has no address yet (needs elevation)

{ipscout-2.0.0 → ipscout-2.1.0}/docs/systemdesign/module_reference.md

@@ -58,7 +58,7 @@ The import-linter contract `Layered dependencies point one way only` is enforced
 listed highest first; each may import only from those below it.
 
 ```
-scan : subnet : portscan : mtu : wol   sweeps and single-purpose probes
+scan : subnet : portscan : banner : mtu : wol : dhcp   sweeps and single-purpose probes
 api          ping / aping / ping_many / aping_many / is_reachable / ais_reachable
 traceroute   traceroute / atraceroute / trace_path / atrace_path
 static_neighbours  set_neighbour / remove_neighbour
@@ -71,7 +71,9 @@ transport_posix : transport_windows : transport_tcp
   : interfaces_posix : interfaces_windows
   : routes_linux : routes_macos : routes_windows
   : neighbours_linux : neighbours_macos : neighbours_windows
+  : dhcp_linux : dhcp_windows : dhcp_macos
 packet : resolve : ports : winapi : netlink : bsdroute : arp : tcpsyn
+  : pool : sockerr : unixio : bootp : bpf
 models
 errors
 ```
@@ -208,6 +210,7 @@ own value only as a fallback, which keeps loopback and LAN timings meaningful.
 | `scan.py`              | `arp_scan`, `find_ip_by_mac`, `local_networks`, `sweep_scope`. Sweep, then read what the kernel learned.                          |
 | `subnet.py`            | `subnet_info`, composing interfaces, routes and the stored lease.                                                                 |
 | `portscan.py`          | `scan_ports`, `ascan_ports`, `syn_scan`, `parse_ports`.                                                                           |
+| `banner.py`            | `grab_banners`, `agrab_banners`: connect, read the first line, say goodbye and close, all on one connection per host.             |
 | `mtu.py`               | `path_mtu`, by kernel query on Linux and by bisection elsewhere.                                                                  |
 | `wol.py`               | `wake_on_lan` and the magic packet it builds.                                                                                     |
 | `dhcp.py`              | `observe_dhcp` and its session: the capture loop, the quiet window and the platform dispatch.                                     |
@@ -229,6 +232,8 @@ own value only as a fallback, which keeps loopback and LAN timings meaningful.
 | `bootp.py`    | BOOTP/DHCP reply codec, separate from the capture for the same reason.                                                  |
 | `bpf.py`      | BSD packet filter ioctl encoding and record splitting, shared by two backends.                                          |
 | `tcpsyn.py`   | TCP SYN codec and its pseudo-header checksum, for the half-open scan.                                                   |
+| `pool.py`     | `gather_bounded`: a fixed worker pool, so a long work list never becomes one Task per item.                             |
+| `sockerr.py`  | `is_refusal`: one reading of a refused connect across every platform's spelling, shared by every module that connects.  |
 
 ### Platform backends
 
@@ -255,7 +260,7 @@ own value only as a fallback, which keeps loopback and LAN timings meaningful.
 
 | Module              | Role                                                                       |
 |---------------------|----------------------------------------------------------------------------|
-| `cli.py`            | The rich-click group, twenty-one subcommands, `_emit` and `_fail`, `main`. |
+| `cli.py`            | The rich-click group, twenty-two subcommands, `_emit` and `_fail`, `main`. |
 | `serialize.py`      | `to_jsonable` and `dumps` at the output boundary.                          |
 | `typed_click.py`    | Typed facade over rich-click's partially-typed decorators.                 |
 | `__main__.py`       | `python -m ipscout`.                                                       |

{ipscout-2.0.0 → ipscout-2.1.0}/docs/usage.md

@@ -487,6 +487,36 @@ ipscout.scan_ports(host, "1-1024", method=ipscout.ScanMethod.SYN)
 Both methods hold only `concurrency` probes alive at a time, so a full-range scan is bounded in
 memory rather than allocating a task per port.
 
+## Reading a banner
+
+Many services announce themselves the moment a client connects: an FTP or SMTP server sends a `220`
+line, an SSH server its version string. `grab_banners` reads that first line from many hosts at once,
+which is how a device is identified by what it says rather than by which port it has open:
+
+```python
+results = ipscout.grab_banners(["192.0.2.10", "192.0.2.11"], 21, farewell=b"QUIT\r\n")
+for host, banner in results.items():
+    if banner.line is not None and banner.line.startswith("220 Print Server"):
+        print(host, banner.line)  # 192.0.2.10 220 Print Server Ready.
+```
+
+Match the part of the greeting that names the device: every FTP server sends a `220` line.
+
+Each `Banner` carries one of four states. `GREETED` holds the decoded first line in `line`, and only
+a `GREETED` result has one, so `banner.line is not None` is the same test and narrows the type; `SILENT`
+means the host accepted the connection and sent nothing before the deadline; `REFUSED` means the port
+actively refused; `UNREACHABLE` puts the reason in `error`, and also covers a name that did not
+resolve, so one bad name never costs the other results.
+
+Everything for one host happens on a single connection: connect, read up to the first newline (at
+most `max_line_bytes`, 512 by default), send `farewell` if given and a line was read, close. Some
+embedded servers refuse a new connection for a moment after each session, so scanning for open
+ports first and connecting again to read misses exactly the devices a banner identifies.
+
+`timeout` (3.0 s by default) is one deadline per host for resolving, connecting and reading
+together. A refused connection is reported rather than retried; retry it yourself when the device is
+known to need it. `agrab_banners` is the same on the event loop.
+
 ## Waking a host, and the path to it
 
 ```python
@@ -502,7 +532,7 @@ one produces a silent black hole.
 
 ## The CLI
 
-21 commands. `ipscout`, `python -m ipscout` and `uvx ipscout` are the same entry point.
+22 commands. `ipscout`, `python -m ipscout` and `uvx ipscout` are the same entry point.
 
 | Command            | What it does                                                            |
 |--------------------|-------------------------------------------------------------------------|
@@ -522,6 +552,7 @@ one produces a silent black hole.
 | `remove-neighbour` | Delete an IPv4 neighbour entry; exits 1 when there was none.            |
 | `subnet`           | Show addressing, gateway and stored DHCP facts per subnet.              |
 | `scan-ports`       | Report which ports are open, closed or filtered.                        |
+| `banners`          | Read the first line each host sends on a TCP port.                      |
 | `mtu`              | Show the largest packet that reaches a target unfragmented.             |
 | `wake`             | Send a wake-on-LAN magic packet.                                        |
 | `observe-dhcp`     | Watch a DHCP handshake for the addresses offered to a hardware address. |
@@ -542,20 +573,21 @@ Global options, which live on the group so they compose with every subcommand:
 
 Per-command options:
 
-| Command            | Options                                                                                                   |
-|--------------------|-----------------------------------------------------------------------------------------------------------|
-| `ping`             | `--times/-c` (4), `--timeout` (2.0), `--interval` (0.2), `-4`, `-6`, `--tcp-fallback`, `--tcp-port` (443) |
-| `ping-many`        | `--times/-c` (4), `--timeout` (2.0), `--concurrency` (64)                                                 |
-| `reachable`        | `--timeout` (2.0), `--tcp-port` (443)                                                                     |
-| `traceroute`       | `--max-hops` (30), `--timeout` (2.0), `-4`, `-6`, `--resolve-names`                                       |
-| `resolve`          | `-4`, `-6`                                                                                                |
-| `reverse-dns`      | none beyond the global flags                                                                              |
-| `interfaces`       | none beyond the global flags                                                                              |
-| `observe-dhcp`     | `--interface` (the default route's), `--timeout` (60.0), `--settle` (12.0)                                |
-| `set-neighbour`    | `--interface` (the one whose subnet holds IP)                                                             |
-| `remove-neighbour` | `--interface` (every interface the cache lists IP on)                                                     |
-| `capabilities`     | none beyond the global flags                                                                              |
-| `info`             | none beyond the global flags                                                                              |
+| Command            | Options                                                                                                          |
+|--------------------|------------------------------------------------------------------------------------------------------------------|
+| `ping`             | `--times/-c` (4), `--timeout` (2.0), `--interval` (0.2), `-4`, `-6`, `--tcp-fallback`, `--tcp-port` (443)        |
+| `ping-many`        | `--times/-c` (4), `--timeout` (2.0), `--concurrency` (64)                                                        |
+| `reachable`        | `--timeout` (2.0), `--tcp-port` (443)                                                                            |
+| `traceroute`       | `--max-hops` (30), `--timeout` (2.0), `-4`, `-6`, `--resolve-names`                                              |
+| `resolve`          | `-4`, `-6`                                                                                                       |
+| `reverse-dns`      | none beyond the global flags                                                                                     |
+| `interfaces`       | none beyond the global flags                                                                                     |
+| `banners`          | `--port` (required), `--timeout` (3.0), `--concurrency` (64), `--max-line-bytes` (512), `--farewell`, `-4`, `-6` |
+| `observe-dhcp`     | `--interface` (the default route's), `--timeout` (60.0), `--settle` (12.0)                                       |
+| `set-neighbour`    | `--interface` (the one whose subnet holds IP)                                                                    |
+| `remove-neighbour` | `--interface` (every interface the cache lists IP on)                                                            |
+| `capabilities`     | none beyond the global flags                                                                                     |
+| `info`             | none beyond the global flags                                                                                     |
 
 `-4` and `-6` are mutually exclusive.
 
@@ -576,6 +608,7 @@ ipscout find-ip dc:b2:2f:44:34:59 --scan  # which addresses hold a MAC
 ipscout arp-scan --network 192.168.1.0/24 # sweep, then read what was learned
 ipscout subnet                            # addressing, gateway, stored DHCP facts
 ipscout scan-ports 192.168.1.10 --ports 22,80,443,8000-8100
+ipscout banners 192.0.2.0/24 --port 21 --farewell 'QUIT\r\n'   # each host's greeting; networks expand
 ipscout mtu 8.8.8.8
 ipscout wake aa:bb:cc:dd:ee:ff --broadcast 192.168.1.255
 ipscout observe-dhcp 02:00:5e:10:00:00 --interface br0   # needs root; last line is the bound address
@@ -747,12 +780,12 @@ print(muted.reached, muted.error)
 
 ## Public surface
 
-Everything below is exported from the package root. This table is generated from
-
-`ipscout.__all__`, so a name here is a name that exists.
+Everything below is exported from the package root, and every name in `ipscout.__all__` is listed
+here or, for the exceptions, in the paragraph below the tables.
 
 | Name                           | Kind      | Purpose                                                           |
 |--------------------------------|-----------|-------------------------------------------------------------------|
+| `agrab_banners`                | coroutine | The same banner grab, on the event loop.                          |
 | `ais_reachable`                | coroutine | The same contract, on the event loop.                             |
 | `aping`                        | coroutine | The same, without blocking the event loop.                        |
 | `aping_many`                   | coroutine | Probe many targets concurrently.                                  |
@@ -763,6 +796,7 @@ Everything below is exported from the package root. This table is generated from
 | `default_gateway`              | function  | The route used when nothing more specific matches.                |
 | `find_ip_by_mac`               | function  | Which addresses currently hold a hardware address.                |
 | `get_mac_address`              | function  | The direct layer-2 address, or None for anything routed.          |
+| `grab_banners`                 | function  | The first line each host sends on a TCP port, on one connection.  |
 | `icmp_available`               | function  | Whether an ICMP probe could be made right now, per family.        |
 | `is_reachable`                 | function  | Total yes-or-no shortcut. Never raises, always falls back to TCP. |
 | `local_interfaces`             | function  | Every local network interface.                                    |
@@ -796,6 +830,7 @@ Result models, all frozen Pydantic models with `extra="forbid"`:
 
 | Name                 | Returned by                                      |
 |----------------------|--------------------------------------------------|
+| `Banner`             | grab_banners, agrab_banners                      |
 | `CapabilityReport`   | the capabilities CLI command                     |
 | `Interface`          | local_interfaces                                 |
 | `InterfaceAddress`   | the ipv4 and ipv6 fields of Interface            |
@@ -817,6 +852,7 @@ Enums, all `str` subclasses so their members are already strings on the wire:
 | Name             | Members                                                |
 |------------------|--------------------------------------------------------|
 | `AddressFamily`  | IPV4, IPV6                                             |
+| `BannerState`    | GREETED, SILENT, REFUSED, UNREACHABLE                  |
 | `CommandName`    | one member per CLI subcommand                          |
 | `MacScope`       | DIRECT, NEXT_HOP, UNKNOWN                              |
 | `NeighbourState` | REACHABLE, STALE, PERMANENT, INCOMPLETE, FAILED, OTHER |

{ipscout-2.0.0 → ipscout-2.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipscout"
-version = "2.0.0"
+version = "2.1.0"
 description = "Ping, traceroute and local-network inspection in pure Python - no subprocess, and no admin rights on the default paths"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -68,7 +68,7 @@ dev = [
   "import-linter>=2.15",
   "setuptools>=84.2.1",
   "rtoml>=0.14.0",
-  "certifi>=2026.10.19",  # PYSEC-2026-4320
+  "certifi>=2026.10.23",  # PYSEC-2026-4320
 ]
 
 [project.scripts]
@@ -263,7 +263,7 @@ root_package = "ipscout"
 name = "Layered dependencies point one way only"
 type = "layers"
 layers = [
-  "ipscout.scan : ipscout.subnet : ipscout.portscan : ipscout.mtu : ipscout.wol : ipscout.dhcp",
+  "ipscout.scan : ipscout.subnet : ipscout.portscan : ipscout.banner : ipscout.mtu : ipscout.wol : ipscout.dhcp",
   "ipscout.api",
   "ipscout.traceroute",
   "ipscout.static_neighbours",
@@ -273,7 +273,7 @@ layers = [
   "ipscout.service",
   "ipscout.factory",
   "ipscout.transport_posix : ipscout.transport_windows : ipscout.transport_tcp : ipscout.interfaces_posix : ipscout.interfaces_windows : ipscout.routes_linux : ipscout.routes_macos : ipscout.routes_windows : ipscout.neighbours_linux : ipscout.neighbours_macos : ipscout.neighbours_windows : ipscout.dhcp_linux : ipscout.dhcp_windows : ipscout.dhcp_macos",
-  "ipscout.packet : ipscout.resolve : ipscout.ports : ipscout.winapi : ipscout.netlink : ipscout.bsdroute : ipscout.arp : ipscout.tcpsyn : ipscout.pool : ipscout.unixio : ipscout.bootp : ipscout.bpf",
+  "ipscout.packet : ipscout.resolve : ipscout.ports : ipscout.winapi : ipscout.netlink : ipscout.bsdroute : ipscout.arp : ipscout.tcpsyn : ipscout.pool : ipscout.sockerr : ipscout.unixio : ipscout.bootp : ipscout.bpf",
   "ipscout.models",
   "ipscout.errors",
 ]

{ipscout-2.0.0 → ipscout-2.1.0}/src/ipscout/__init__.py

@@ -37,6 +37,7 @@ from .api import (
     ping,
     ping_many,
 )
+from .banner import agrab_banners, grab_banners
 from .dhcp import (
     DhcpSession,
     dhcp_capture_available,
@@ -57,6 +58,8 @@ from .factory import icmp_available
 from .interfaces import local_interfaces
 from .models import (
     AddressFamily,
+    Banner,
+    BannerState,
     CapabilityReport,
     CommandName,
     Interface,
@@ -92,6 +95,8 @@ from .wol import wake_on_lan
 
 __all__ = [
     "AddressFamily",
+    "Banner",
+    "BannerState",
     "CapabilityReport",
     "CommandName",
     "DhcpSession",
@@ -121,6 +126,7 @@ __all__ = [
     "SubnetInfo",
     "SweepScope",
     "TraceHop",
+    "agrab_banners",
     "ais_reachable",
     "aping",
     "aping_many",
@@ -132,6 +138,7 @@ __all__ = [
     "dhcp_capture_available",
     "find_ip_by_mac",
     "get_mac_address",
+    "grab_banners",
     "icmp_available",
     "is_reachable",
     "local_interfaces",

{ipscout-2.0.0 → ipscout-2.1.0}/src/ipscout/__init__conf__.py

@@ -26,7 +26,7 @@ name = "ipscout"
 #: Human-readable summary shown in CLI help output.
 title = "Ping, traceroute and local-network inspection in pure Python - no subprocess, and no admin rights on the default paths"
 #: Current release version pulled from ``pyproject.toml`` by automation.
-version = "2.0.0"
+version = "2.1.0"
 #: Repository homepage presented to users.
 homepage = "https://github.com/bitranox/ipscout"
 #: Author attribution surfaced in CLI output.

{ipscout-2.0.0 → ipscout-2.1.0}/src/ipscout/api.py

@@ -285,12 +285,12 @@ async def aping_many(  # noqa: PLR0913 - public API: every knob is keyword-only
     # A worker pool rather than a semaphore inside a gather over everything:
     # the semaphore bounds probes in flight while still creating one Task per
     # target up front, so a sweep of a large subnet holds them all at once.
-    completed = await gather_bounded(unique, one, concurrency)
-    results = dict(completed)
-    if len(results) != len(unique):  # pragma: no cover - a lost result is a bug, not a condition
-        msg = f"sweep returned {len(results)} results for {len(unique)} targets"
+    completed = dict(await gather_bounded(unique, one, concurrency))
+    if len(completed) != len(unique):  # pragma: no cover - a lost result is a bug, not a condition
+        msg = f"sweep returned {len(completed)} results for {len(unique)} targets"
         raise RuntimeError(msg)
-    return results
+    # Rebuilt from the input list: the pool's own order is completion order.
+    return {target: completed[target] for target in unique}
 
 
 def ping_many(  # noqa: PLR0913 - public API: every knob is keyword-only and independently useful

ipscout-2.1.0/src/ipscout/banner.py

@@ -0,0 +1,287 @@
+"""Banner grabs: what each host says first on a TCP port, read on one connection.
+
+Contents:
+    grab_banners / agrab_banners: The first line many hosts send on one port.
+
+Note:
+    Everything for one host happens on ONE connection - connect, read the
+    greeting, optionally say goodbye, close. That is not a convenience: some
+    embedded servers refuse a new connect for a moment after each session
+    (measured on a print server: about 0.1 s), so "find the open ports, then
+    connect again to read" misses exactly the devices a banner identifies.
+
+    One deadline per host covers name resolution, the connect and the read
+    together, so a caller's ``timeout`` bounds how long any one host can take,
+    rather than each phase taking up to that long on its own.
+
+    A refused connection is reported, not retried. Whether a refusal is worth a
+    second try depends on the device, and only the caller knows the device.
+
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import socket
+from typing import TYPE_CHECKING, NamedTuple, TypeVar
+
+from .errors import IPScoutError
+from .models import AddressFamily, Banner, BannerState
+from .pool import gather_bounded
+from .resolve import resolve_one
+from .sockerr import is_refusal
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine, Iterable
+
+__all__ = ["DEFAULT_CONCURRENCY", "DEFAULT_MAX_LINE_BYTES", "DEFAULT_TIMEOUT", "agrab_banners", "grab_banners"]
+
+#: Connections in flight at once. Enough for a /24 in a few rounds while
+#: staying far from any per-process file-handle limit.
+DEFAULT_CONCURRENCY = 64
+
+#: Seconds per host. Generous on purpose: with dozens of connects in flight a
+#: present but slow embedded device was measured taking over 2 s to accept.
+DEFAULT_TIMEOUT = 3.0
+
+#: A greeting is one short line; this bounds what a hostile or chatty server
+#: can make the caller buffer per host.
+DEFAULT_MAX_LINE_BYTES = 512
+
+_MIN_PORT = 1
+_MAX_PORT = 65535
+
+_SOCKET_FAMILY = {AddressFamily.IPV4: socket.AF_INET, AddressFamily.IPV6: socket.AF_INET6}
+
+_T = TypeVar("_T")
+
+
+class _Settings(NamedTuple):
+    """The per-grab knobs, bundled so every host is grabbed the same way."""
+
+    port: int
+    timeout: float
+    max_line_bytes: int
+    farewell: bytes | None
+    family: AddressFamily | None
+
+
+def _validate(settings: _Settings, concurrency: int) -> None:
+    """Refuse an argument that could never produce a useful grab, before any connect."""
+
+    if not _MIN_PORT <= settings.port <= _MAX_PORT:
+        msg = f"port must be {_MIN_PORT}-{_MAX_PORT}, got {settings.port}"
+        raise ValueError(msg)
+    if not settings.timeout > 0:
+        msg = f"timeout must be greater than 0 seconds, got {settings.timeout}"
+        raise ValueError(msg)
+    if settings.max_line_bytes < 1:
+        msg = f"max_line_bytes must be at least 1, got {settings.max_line_bytes}"
+        raise ValueError(msg)
+    if concurrency < 1:
+        msg = f"concurrency must be at least 1, got {concurrency}"
+        raise ValueError(msg)
+
+
+async def _within(deadline: float, awaitable: Coroutine[object, object, _T]) -> _T:
+    """Await ``awaitable`` with whatever is left until ``deadline``.
+
+    Raises:
+        TimeoutError: The deadline has passed or passes while waiting. Raised
+            as the builtin on every version, so callers need not also catch
+            ``asyncio.TimeoutError``, which is a different class before 3.11.
+    """
+
+    remaining = deadline - asyncio.get_running_loop().time()
+    if remaining <= 0:
+        awaitable.close()
+        raise TimeoutError
+    try:
+        return await asyncio.wait_for(awaitable, remaining)
+    except asyncio.TimeoutError as exc:
+        raise TimeoutError from exc
+
+
+async def _read_line(reader: asyncio.StreamReader, deadline: float, cap: int) -> bytes:
+    """Read until a newline, the close, ``cap`` bytes or the deadline - whichever comes first.
+
+    Whatever arrived by then is the line, terminator excluded: a server that
+    writes a partial greeting and hangs up has still said something.
+    """
+
+    received = bytearray()
+    while len(received) < cap:
+        try:
+            chunk = await _within(deadline, reader.read(cap - len(received)))
+        except OSError:  # TimeoutError included: the deadline ends the line too
+            break
+        if not chunk:
+            break
+        end = chunk.find(b"\n")
+        if end >= 0:
+            received += chunk[:end]
+            break
+        received += chunk
+    return bytes(received)
+
+
+async def _say_goodbye(writer: asyncio.StreamWriter, farewell: bytes) -> None:
+    """Send the farewell; a peer that already left changes nothing about what it said."""
+
+    with contextlib.suppress(OSError):
+        writer.write(farewell)
+        await writer.drain()
+
+
+async def _close(writer: asyncio.StreamWriter) -> None:
+    writer.close()
+    with contextlib.suppress(OSError, asyncio.TimeoutError, ConnectionError):
+        await writer.wait_closed()
+
+
+async def _converse(host: str, reader: asyncio.StreamReader, writer: asyncio.StreamWriter, settings: _Settings, deadline: float) -> Banner:
+    """Read the greeting on an open connection, say goodbye if asked, and close it."""
+
+    try:
+        raw = await _read_line(reader, deadline, settings.max_line_bytes)
+        if raw and settings.farewell:
+            await _say_goodbye(writer, settings.farewell)
+    finally:
+        await _close(writer)
+    if not raw:
+        return Banner(host=host, port=settings.port, state=BannerState.SILENT)
+    line = raw.decode("utf-8", errors="replace").strip()
+    return Banner(host=host, port=settings.port, state=BannerState.GREETED, line=line)
+
+
+async def _grab_one(host: str, settings: _Settings) -> Banner:
+    """Grab one host's banner. Every failure is a result, never a raise."""
+
+    deadline = asyncio.get_running_loop().time() + settings.timeout
+
+    def unreachable(reason: str) -> Banner:
+        return Banner(host=host, port=settings.port, state=BannerState.UNREACHABLE, error=reason)
+
+    try:
+        # In a thread: a slow DNS answer for one name must not stall every other host.
+        target = await _within(deadline, asyncio.to_thread(resolve_one, host, family=settings.family))
+        family = _SOCKET_FAMILY[target.family]
+        reader, writer = await _within(deadline, asyncio.open_connection(target.address, settings.port, family=family))
+    except IPScoutError as exc:
+        return unreachable(str(exc))
+    except TimeoutError:
+        return unreachable(f"no connection within {settings.timeout:g} s")
+    except OSError as exc:
+        if is_refusal(exc):
+            return Banner(host=host, port=settings.port, state=BannerState.REFUSED)
+        return unreachable(str(exc) or type(exc).__name__)
+    return await _converse(host, reader, writer, settings, deadline)
+
+
+async def agrab_banners(  # noqa: PLR0913 - public API: every knob is keyword-only and independently useful
+    hosts: Iterable[str],
+    port: int,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_line_bytes: int = DEFAULT_MAX_LINE_BYTES,
+    farewell: bytes | None = None,
+    concurrency: int = DEFAULT_CONCURRENCY,
+    family: AddressFamily | None = None,
+) -> dict[str, Banner]:
+    """Read the first line each host sends on a TCP port, many hosts at once.
+
+    Args:
+        hosts: Hostnames or address literals; a link-local IPv6 address needs
+            its ``%zone``. Duplicates are collapsed, since the result is keyed
+            by host and a repeat could only overwrite itself.
+        port: The TCP port to connect to on every host.
+        timeout: Seconds allowed per host for resolving, connecting and
+            reading together. A host that connects but has not finished its
+            line by then returns what it sent so far.
+        max_line_bytes: The most bytes of greeting kept per host. Reading stops
+            at the first newline, at the close, or here.
+        farewell: Bytes to send after a line was read and before closing, such
+            as ``b"QUIT\\r\\n"`` for FTP or SMTP, so the server logs a clean exit
+            rather than a dropped session. Sent to any host that said
+            something, and never to one that stayed silent.
+        concurrency: Connections in flight at once.
+        family: Use only IPv4 or IPv6 addresses for every host.
+
+    Returns:
+        A mapping of host, exactly as given, to its :class:`Banner`, in the
+        order the hosts were given. Every host has an entry: a name that does
+        not resolve is an UNREACHABLE result, never an exception.
+
+    Raises:
+        ValueError: ``port`` is outside 1-65535, or ``timeout``,
+            ``max_line_bytes`` or ``concurrency`` is not positive. Raised
+            before anything connects.
+
+    Examples:
+        >>> import asyncio
+        >>> results = asyncio.run(agrab_banners(["nothing.invalid"], 21))
+        >>> results["nothing.invalid"].state
+        <BannerState.UNREACHABLE: 'unreachable'>
+
+    """
+
+    settings = _Settings(port, timeout, max_line_bytes, farewell, family)
+    _validate(settings, concurrency)
+    unique = list(dict.fromkeys(hosts))
+
+    async def one(host: str) -> tuple[str, Banner]:
+        # Paired with its host: the pool completes out of order.
+        return host, await _grab_one(host, settings)
+
+    completed = dict(await gather_bounded(unique, one, concurrency))
+    return {host: completed[host] for host in unique}
+
+
+def grab_banners(  # noqa: PLR0913 - public API: every knob is keyword-only and independently useful
+    hosts: Iterable[str],
+    port: int,
+    *,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_line_bytes: int = DEFAULT_MAX_LINE_BYTES,
+    farewell: bytes | None = None,
+    concurrency: int = DEFAULT_CONCURRENCY,
+    family: AddressFamily | None = None,
+) -> dict[str, Banner]:
+    """Read the first line each host sends on a TCP port, from synchronous code.
+
+    Takes the same arguments as :func:`agrab_banners`.
+
+    Returns:
+        A mapping of host to :class:`Banner`, in the order the hosts were given.
+
+    Raises:
+        ValueError: As :func:`agrab_banners`.
+        RuntimeError: Called from inside a running event loop, where it would
+            deadlock. Await :func:`agrab_banners` there instead.
+
+    Examples:
+        >>> grab_banners(["nothing.invalid"], 21)["nothing.invalid"].state
+        <BannerState.UNREACHABLE: 'unreachable'>
+
+    """
+
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        pass
+    else:
+        msg = "grab_banners() cannot run inside an event loop; await agrab_banners() instead"
+        raise RuntimeError(msg)
+
+    return asyncio.run(
+        agrab_banners(
+            hosts,
+            port,
+            timeout=timeout,
+            max_line_bytes=max_line_bytes,
+            farewell=farewell,
+            concurrency=concurrency,
+            family=family,
+        )
+    )