lanname 0.1.0__tar.gz

lanname-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mjaksn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lanname-0.1.0/PKG-INFO

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: lanname
+Version: 0.1.0
+Summary: Address to hostname lookup on a local network: reverse DNS, mDNS and NetBIOS, cached and non-blocking, standard library only
+Author: mjaksn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mjaksn/lanname
+Project-URL: Source, https://github.com/mjaksn/lanname
+Project-URL: Issues, https://github.com/mjaksn/lanname/issues
+Project-URL: Changelog, https://github.com/mjaksn/lanname/blob/main/CHANGELOG.md
+Keywords: dns,mdns,netbios,hostname,resolver,lan,reverse-dns
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: System :: Networking
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lanname
+
+[![CI](https://github.com/mjaksn/lanname/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/lanname/actions/workflows/ci.yml)
+[![Release](https://github.com/mjaksn/lanname/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/lanname/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/lanname/blob/main/LICENSE)
+
+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.
+
+```python
+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 properties are worth stating before anything else, because they are the
+reasons to reach for this rather than call `socket.gethostbyaddr` yourself.
+
+**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.
+
+**It is off until you ask.** The widest mode sends probes onto the LAN. A
+library that did that unasked, inside a daemon somebody installed for an
+unrelated reason, would be doing something the caller never sanctioned on a
+network they may not own.
+
+---
+
+## Contents
+
+- [Installing](#installing)
+- [Modes](#modes)
+- [Resolver](#resolver)
+- [What gets looked up](#what-gets-looked-up)
+- [Static hosts files](#static-hosts-files)
+- [What answered, over a session](#what-answered-over-a-session)
+- [Counters](#counters)
+- [Ceilings](#ceilings)
+- [Logging](#logging)
+- [The three methods on their own](#the-three-methods-on-their-own)
+- [Limitations](#limitations)
+- [Licence](#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.
+
+```python
+import lanname
+lanname.__version__          # "0.1.0"
+```
+
+---
+
+## Modes
+
+| mode | |
+| --- | --- |
+| `"off"` | the default. No lookups, no threads, no traffic. |
+| `"dns"` | reverse DNS only. Passive in the sense that it asks the resolver the machine already uses, but it is still a query per address. |
+| `"all"` | reverse DNS, then mDNS to 224.0.0.251, then a NetBIOS status query to the host itself. **This sends probes onto the LAN.** |
+
+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 but leaves the threads
+parked on an empty queue; `shutdown()` is what retires them.
+
+---
+
+## Resolver
+
+```python
+Resolver(mode="off", hosts_files=(), workers=4, resolve_public=False,
+         fqdn=False, positive_ttl=3600, negative_ttl=300, timeout=1.0)
+```
+
+| argument | |
+| --- | --- |
+| `mode` | one of the three above. `ValueError` for anything else. |
+| `hosts_files` | paths to hosts-format files, read once at construction. See [below](#static-hosts-files). |
+| `workers` | background lookup threads. They are daemons, and none are started at all while the mode is `"off"`. |
+| `resolve_public` | look up public addresses too, default `False`. See [what gets looked up](#what-gets-looked-up). |
+| `fqdn` | keep the full name rather than the first label. `False` gives `nas`, `True` gives `nas.local`. |
+| `positive_ttl` | seconds a found name is cached, default 3600. |
+| `negative_ttl` | seconds a failure is cached, default 300, so a host that does not answer is not asked again on every sighting. |
+| `timeout` | per probe, in seconds, for mDNS and NetBIOS. Reverse DNS uses the system resolver's own timeout. |
+
+| method | |
+| --- | --- |
+| `lookup(addr)` | the name, or `None`. Never blocks. |
+| `set_mode(mode)` | change mode while running, starting workers if needed. |
+| `set_fqdn(fqdn)` | change the name form. Empties the cache, since every entry in it was shortened on the way in. |
+| `local_hosts()` | every private address seen with a name, and the names it answered to. See [below](#what-answered-over-a-session). |
+| `shutdown()` | ask the workers to stop. Also `__exit__`, so a `with` block does it. |
+
+`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.
+
+---
+
+## What gets looked up
+
+Not everything is worth a query, and two of the categories are worth refusing
+outright.
+
+| kind | looked up |
+| --- | --- |
+| private | yes, by every mode. This is what the package is for. |
+| public | only with `resolve_public=True` |
+| multicast | never |
+| loopback, link-local, reserved, unspecified | never |
+| not an address at all | never |
+
+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
+
+```python
+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
+
+```python
+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.
+
+| key | |
+| --- | --- |
+| `hits` | answered from the cache |
+| `resolved` | a worker found a name |
+| `missed` | a worker found nothing, and the failure was cached for `negative_ttl` |
+| `via_dns`, `via_mdns`, `via_netbios` | which method produced the name, for the ones that were found |
+| `dropped` | lookups discarded because the work queue was full |
+| `evicted` | cache entries dropped to stay under the ceiling |
+
+`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.
+
+| constant | default | what it bounds | on overflow |
+| --- | --- | --- | --- |
+| `lanname.resolver.RESOLVER_CACHE_MAX` | 50,000 | cached names | least recently used evicted, counted in `stats["evicted"]` |
+| `lanname.resolver.MAX_OBSERVED_HOSTS` | 5,000 | addresses remembered for `local_hosts()` | least recently seen evicted |
+| `lanname.resolver.MAX_NAMES_PER_HOST` | 5 | names remembered for any one address | oldest forgotten |
+| `lanname.addrs.MAX_ADDR_KIND_CACHE` | 100,000 | cached address classifications | stops caching |
+
+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.
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+| logger | what |
+| --- | --- |
+| `lanname.resolver` | WARNING for a hosts file that could not be read, DEBUG for a lookup that raised |
+
+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:
+
+```python
+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. 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.
+
+---
+
+## 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 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.
+- **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](https://github.com/mjaksn/lanname/blob/main/LICENSE).

lanname-0.1.0/README.md

@@ -0,0 +1,303 @@
+# lanname
+
+[![CI](https://github.com/mjaksn/lanname/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/lanname/actions/workflows/ci.yml)
+[![Release](https://github.com/mjaksn/lanname/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/lanname/actions/workflows/release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/lanname/blob/main/LICENSE)
+
+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.
+
+```python
+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 properties are worth stating before anything else, because they are the
+reasons to reach for this rather than call `socket.gethostbyaddr` yourself.
+
+**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.
+
+**It is off until you ask.** The widest mode sends probes onto the LAN. A
+library that did that unasked, inside a daemon somebody installed for an
+unrelated reason, would be doing something the caller never sanctioned on a
+network they may not own.
+
+---
+
+## Contents
+
+- [Installing](#installing)
+- [Modes](#modes)
+- [Resolver](#resolver)
+- [What gets looked up](#what-gets-looked-up)
+- [Static hosts files](#static-hosts-files)
+- [What answered, over a session](#what-answered-over-a-session)
+- [Counters](#counters)
+- [Ceilings](#ceilings)
+- [Logging](#logging)
+- [The three methods on their own](#the-three-methods-on-their-own)
+- [Limitations](#limitations)
+- [Licence](#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.
+
+```python
+import lanname
+lanname.__version__          # "0.1.0"
+```
+
+---
+
+## Modes
+
+| mode | |
+| --- | --- |
+| `"off"` | the default. No lookups, no threads, no traffic. |
+| `"dns"` | reverse DNS only. Passive in the sense that it asks the resolver the machine already uses, but it is still a query per address. |
+| `"all"` | reverse DNS, then mDNS to 224.0.0.251, then a NetBIOS status query to the host itself. **This sends probes onto the LAN.** |
+
+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 but leaves the threads
+parked on an empty queue; `shutdown()` is what retires them.
+
+---
+
+## Resolver
+
+```python
+Resolver(mode="off", hosts_files=(), workers=4, resolve_public=False,
+         fqdn=False, positive_ttl=3600, negative_ttl=300, timeout=1.0)
+```
+
+| argument | |
+| --- | --- |
+| `mode` | one of the three above. `ValueError` for anything else. |
+| `hosts_files` | paths to hosts-format files, read once at construction. See [below](#static-hosts-files). |
+| `workers` | background lookup threads. They are daemons, and none are started at all while the mode is `"off"`. |
+| `resolve_public` | look up public addresses too, default `False`. See [what gets looked up](#what-gets-looked-up). |
+| `fqdn` | keep the full name rather than the first label. `False` gives `nas`, `True` gives `nas.local`. |
+| `positive_ttl` | seconds a found name is cached, default 3600. |
+| `negative_ttl` | seconds a failure is cached, default 300, so a host that does not answer is not asked again on every sighting. |
+| `timeout` | per probe, in seconds, for mDNS and NetBIOS. Reverse DNS uses the system resolver's own timeout. |
+
+| method | |
+| --- | --- |
+| `lookup(addr)` | the name, or `None`. Never blocks. |
+| `set_mode(mode)` | change mode while running, starting workers if needed. |
+| `set_fqdn(fqdn)` | change the name form. Empties the cache, since every entry in it was shortened on the way in. |
+| `local_hosts()` | every private address seen with a name, and the names it answered to. See [below](#what-answered-over-a-session). |
+| `shutdown()` | ask the workers to stop. Also `__exit__`, so a `with` block does it. |
+
+`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.
+
+---
+
+## What gets looked up
+
+Not everything is worth a query, and two of the categories are worth refusing
+outright.
+
+| kind | looked up |
+| --- | --- |
+| private | yes, by every mode. This is what the package is for. |
+| public | only with `resolve_public=True` |
+| multicast | never |
+| loopback, link-local, reserved, unspecified | never |
+| not an address at all | never |
+
+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
+
+```python
+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
+
+```python
+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.
+
+| key | |
+| --- | --- |
+| `hits` | answered from the cache |
+| `resolved` | a worker found a name |
+| `missed` | a worker found nothing, and the failure was cached for `negative_ttl` |
+| `via_dns`, `via_mdns`, `via_netbios` | which method produced the name, for the ones that were found |
+| `dropped` | lookups discarded because the work queue was full |
+| `evicted` | cache entries dropped to stay under the ceiling |
+
+`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.
+
+| constant | default | what it bounds | on overflow |
+| --- | --- | --- | --- |
+| `lanname.resolver.RESOLVER_CACHE_MAX` | 50,000 | cached names | least recently used evicted, counted in `stats["evicted"]` |
+| `lanname.resolver.MAX_OBSERVED_HOSTS` | 5,000 | addresses remembered for `local_hosts()` | least recently seen evicted |
+| `lanname.resolver.MAX_NAMES_PER_HOST` | 5 | names remembered for any one address | oldest forgotten |
+| `lanname.addrs.MAX_ADDR_KIND_CACHE` | 100,000 | cached address classifications | stops caching |
+
+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.
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+| logger | what |
+| --- | --- |
+| `lanname.resolver` | WARNING for a hosts file that could not be read, DEBUG for a lookup that raised |
+
+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:
+
+```python
+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. 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.
+
+---
+
+## 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 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.
+- **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](https://github.com/mjaksn/lanname/blob/main/LICENSE).