lanname

Address to hostname lookup on a local network: reverse DNS, mDNS and NetBIOS, cached and never blocking the caller. Standard library only, no dependencies, Python 3.9 and up.

from lanname import Resolver

with Resolver(mode="dns", workers=4) as resolver:
    name = resolver.lookup("192.168.1.10")     # None until it is known

An IP address in a log line, a database row or a dashboard is much less useful a year later than the name of the thing it was. The three ways to find that name on a local network are all short, all standard library, and all annoying enough to get right that nobody wants to write them twice.

Two things are worth stating before anything else. The first is why you would reach for this rather than call socket.gethostbyaddr yourself. The second is the one place it will do something you did not ask for if you let it.

It never blocks. lookup() reads a cache and returns, always. Misses are queued for background workers. A caller draining a socket cannot afford to wait on a DNS round trip, and UDP in particular has no backpressure, so anything that stalls the read loop loses packets silently.

The widest mode probes the LAN, and is not the default. Installing this says you want names. It does not say you want multicast queries and NetBIOS requests going to hosts you happened to see an address for, on a network you may not own. The default asks the resolver your machine already uses and nothing more. "all" is a switch you throw deliberately.

Contents

• Installing
• Modes
• Resolver
• What gets looked up
• Static hosts files
• What answered, over a session
• Counters
• Ceilings
• Logging
• The three methods on their own
• Crafting replies to test against
• Limitations
• Licence

Installing

pip install lanname

Or from a checkout with pip install ., or by copying the lanname/ directory somewhere on the path. There is nothing to build and nothing to install alongside it.

import lanname
lanname.__version__          # "0.3.0"

Modes

The order matters and is not configurable: reverse DNS answers for anything with a real record, mDNS catches the Apple and Linux hosts that publish over multicast, and NetBIOS catches the Windows machines that answer to nothing else. Each step only runs because the one before it came back empty.

mode can be changed on a running resolver with set_mode(), which starts the worker threads if the resolver was constructed "off" and never had any. Going back to "off" stops new work being queued and drops what was already queued, unresolved, so nothing is sent for it; a probe in flight is the last one. The threads stay parked on an empty queue; shutdown() is what retires them, and after it the resolver is not restartable: set_mode() still changes the mode but starts nothing.

MODE_DESC is exported with the rest: a dict from each mode name to the one line description of it used above, so a program that offers the choice can say what it is offering without writing its own account of the three.

Resolver

Resolver(mode="dns", hosts_files=(), workers=4, resolve_public=False,
         fqdn=False, positive_ttl=3600, negative_ttl=300, timeout=1.0)

lookup() returning None means "not known yet", never "has no name". Ask again the next time the address turns up; the answer appears once a worker has been round. The first sighting of any address is always a miss, by design.

shutdown() is a courtesy rather than a requirement, since the workers are daemon threads and the interpreter will not wait for them. What it buys is that probes stop going out at the point the caller thinks it has stopped: queued addresses are dropped unresolved, a probe in flight is the last one, and lookup() answers from static entries and the cache only, queueing nothing. A resolver is not restartable; build another.

What gets looked up

Not everything is worth a query, and two of the categories are worth refusing outright.

private means 10/8, 172.16/12, 192.168/16 and fc00::/7, and nothing else. ipaddress's is_private would also say yes to the documentation ranges (192.0.2.0/24 and its two siblings, 2001:db8::/32), the benchmarking range (198.18.0.0/15) and a few more, and its answer has changed between Python versions; none of those is a LAN, and since this class is the gate on what "all" mode probes, it is drawn tightly. Those ranges, and carrier-grade NAT space (100.64.0.0/10), count as public: left alone unless resolve_public is set, and never probed.

Public addresses are skipped by default because a busy link produces thousands of them, most resolve to something uninformative like a cloud provider's generic reverse record, and every one is a query somebody else can see. Turn them on when the public side is the interesting half.

mDNS and NetBIOS are only ever tried for private addresses, whatever resolve_public says. Both are link-local methods, and sending either to an address off the local network is at best pointless and at worst rude.

addr_kind(addr) is exported if the same classification is useful elsewhere. It returns one of ADDR_KINDS.

Static hosts files

Resolver(mode="off", hosts_files=["/etc/hosts", "static.hosts"])

Standard hosts format: an address, whitespace, a name, and # starts a comment. The first entry for an address wins, and files are read in the order given. Lines that do not parse are skipped rather than raising, and a file that cannot be read at all is logged as a warning, on the grounds that a missing optional file should not stop the program that asked for it.

Static entries answer even in "off" mode, and they answer without a cache lookup or a queue round trip. A resolver constructed "off" with a hosts file is a pure static mapping that starts no threads and sends no traffic, which is a reasonable way to run this in an environment where active lookups are not welcome.

What answered, over a session

for addr, names in resolver.local_hosts():
    print(addr, names[0], names[1:] or "")

Every private address that has ever resolved to a name, sorted by address, each with its names most recent first. This is kept separately from the cache and outlives it: the cache expires and evicts, and this is meant to answer "what did you see all session" long after either has happened.

A host whose name changes keeps both, newest first, up to MAX_NAMES_PER_HOST. That is usually a DHCP lease moving or a machine being renamed, and the last few changes are the interesting part.

Counters

resolver.stats is a collections.Counter, safe to read at any time.

dropped climbing means addresses are arriving faster than workers threads can resolve them, and those addresses simply go unresolved for now. Raise workers, or accept it: the queue is bounded on purpose, because the alternative to dropping work is growing memory without limit.

Ceilings

Everything keyed by address has a bound. The addresses reaching this package come off a network, so anything keyed by one and never evicted is a memory leak that other hosts can pull on.

The work queue holds 4,096 addresses and drops rather than blocking, counted in stats["dropped"].

The cache drops its oldest entry rather than emptying itself, and that distinction is the whole reason it is an OrderedDict. Clearing it wholesale would send every active host back through resolution at the same moment, which in "all" mode is a burst of mDNS and NetBIOS probes onto the LAN, from a program that was supposed to be quiet.

Logging

Everything goes to the lanname logger. The package installs a NullHandler and nothing else, so records go nowhere until you configure a handler.

import logging
logging.basicConfig(level=logging.INFO)

Nothing here is logged per address at INFO or above. A resolver watching a busy link would drown any log it shared.

The three methods on their own

The scheduling and the asking are separable, and the asking is exported:

from lanname import mdns_reverse, netbios_name

mdns_reverse("192.168.1.10", timeout=1.0)    # str or None
netbios_name("192.168.1.10", timeout=1.0)    # str or None

Both send one packet and wait for one answer, both block for up to timeout, and both answer None rather than raising when a probe goes unanswered or a reply does not parse, and likewise when no socket can be opened or the send itself fails, as it does on a host with no route to the multicast group. A failure in one method is never a reason for "all" mode to skip the next. Reverse DNS has no wrapper here, because socket.gethostbyaddr already is one.

mdns_reverse sends a PTR query to 224.0.0.251:5353 with the unicast-response bit set and a multicast TTL of 1, so it stays on the link and there is no group to join. netbios_name sends a NBSTAT query straight to the host's port 137 and prefers the unique workstation name out of the answer.

Each takes only the reply to the query it sent. mdns_reverse ignores a datagram from any port but 5353 or carrying another transaction id, and keeps waiting; netbios_name connects to the host so that nothing else can answer, then checks the id and the response bit. A sixteen bit id is a filter for strays and stale replies, not authentication; see Limitations for what is and is not checked about the name itself.

Crafting replies to test against

A name from mDNS or NetBIOS is whatever the answering host chose, so the behaviour worth testing in anything downstream is what it does with a name that is not a tidy label: a control sequence, a newline, an embedded NUL, bytes that are not UTF-8, a lookalike, or a name far longer than a real host would send.

The repository carries a small tool for producing exactly those, under tools/poker. It builds the two replies with the hostname chosen byte for byte, shows what this package reads out of them, and can answer a live resolver's queries on the link so that a whole application sees the name you picked. It is a separate program beside the package, with a window that needs PySide6; the package itself keeps no dependencies. Its README says how to run it and, since it puts spoofed traffic on a network, where not to.

Limitations

• The first answer is always None. That is the design, not a bug. A caller that genuinely needs the name before it can proceed wants socket.gethostbyaddr and the blocking that comes with it.
• mDNS and NetBIOS are IPv4 only. Both open an AF_INET socket. Reverse DNS works for either family, so an IPv6 address gets one method rather than three.
• NetBIOS is a Windows convention and a fading one. Recent Windows can have it disabled, and non-Windows hosts answer only if they run Samba. It is the last method tried for exactly that reason.
• Names are checked, not verified. A host answering NetBIOS or mDNS says what it likes, and nothing here checks the claim against a forward lookup. Treat a name from "all" mode as a label a host chose for itself, not as identity. What is checked is that the name is fit to print: one holding any character below 0x21 (a space is allowed inside a NetBIOS name) or equal to 0x7f is refused, since those move a cursor, forge a second log line or hide the rest of a name; so is a label over 63 bytes or a name over 253, the DNS limits; and a name is abandoned past 255 bytes on the wire, so a reply built to loop its compression pointers cannot inflate one. Everything above 0x7f passes: a lookalike or a right-to-left override is legal in a name and yours to judge. A reverse DNS result goes through the same check, and a refused name is cached as a miss like any other.
• One resolver, one cache. Two resolvers in a process do not share anything, including the worker threads and the queue.

lookup() is safe to call from any thread; the cache and the observed-host table are both behind a lock.

Licence

MIT. See LICENSE.