Resolver Caching Classes

The dnspython resolver does not cache by default, but caching can be enabled by creating a cache and assigning it to the resolver’s cache attribute. If a cache has been configured, the resolver caches both positive and negative responses. The cache respects the DNS TTL of the data, and will not return expired entries.

Two thread-safe cache implementations are provided, a simple dictionary-based Cache, and an LRUCache which provides cache size control suitable for use in web crawlers. Both are subclasses of a common base class which provides basic statistics. The LRUCache can also provide a hits count per cache entry.

class dns.resolver.CacheBase

get_statistics_snapshot() → CacheStatistics

Return a consistent snapshot of all the statistics.

If running with multiple threads, it’s better to take a snapshot than to call statistics methods such as hits() and misses() individually.

hits() → int

How many hits has the cache had?

misses() → int

How many misses has the cache had?

reset_statistics() → None

Reset all statistics to zero.

class dns.resolver.Cache(cleaning_interval: float = 300.0)

Simple thread-safe DNS answer cache.

Initialize the cache.

Parameters:

cleaning_interval (float) – Seconds between periodic cache cleanings.

flush(key: tuple[Name, RdataType, RdataClass] | None = None) → None

Flush the cache.

Parameters:

key – If not None, flush only this entry; otherwise flush the entire cache.

get(key: tuple[Name, RdataType, RdataClass]) → Answer | None

Get the answer associated with key, or None if not cached.

Parameters:

key (tuple[dns.name.Name, dns.rdatatype.RdataType, dns.rdataclass.RdataClass]) – A (name, rdtype, rdclass) tuple identifying the query.

Returns:

The cached answer, or None if not found or expired.

Return type:

dns.resolver.Answer or None

put(key: tuple[Name, RdataType, RdataClass], value: Answer) → None

Associate key with value in the cache.

Parameters:

• key – A (name, rdtype, rdclass) tuple identifying the query.

• value (dns.resolver.Answer) – The answer to cache.

class dns.resolver.LRUCache(max_size: int = 100000)

Thread-safe, bounded, least-recently-used DNS answer cache.

This cache is better than the simple cache (above) if you’re running a web crawler or other process that does a lot of resolutions. The LRUCache has a maximum number of nodes, and when it is full, the least-recently used node is removed to make space for a new one.

Initialize an LRU cache.

Parameters:

max_size (int) – The maximum number of nodes to cache; must be greater than 0.

flush(key: tuple[Name, RdataType, RdataClass] | None = None) → None

Flush the cache.

Parameters:

key (tuple or None) – If not None, flush only this entry; otherwise flush the entire cache. The key is a (dns.name.Name, dns.rdatatype.RdataType, dns.rdataclass.RdataClass) tuple.

get(key: tuple[Name, RdataType, RdataClass]) → Answer | None

Get the answer associated with key.

Returns None if no answer is cached for the key.

Parameters:

key (tuple) – A (dns.name.Name, dns.rdatatype.RdataType, dns.rdataclass.RdataClass) tuple whose values are the query name, rdtype, and rdclass respectively.

Return type:

dns.resolver.Answer or None

get_hits_for_key(key: tuple[Name, RdataType, RdataClass]) → int

Return the number of cache hits associated with the specified key.

put(key: tuple[Name, RdataType, RdataClass], value: Answer) → None

Associate key and value in the cache.

Parameters:

• key (tuple) – A (dns.name.Name, dns.rdatatype.RdataType, dns.rdataclass.RdataClass) tuple whose values are the query name, rdtype, and rdclass respectively.

• value (dns.resolver.Answer) – The answer to cache.

class dns.resolver.CacheStatistics(hits: int = 0, misses: int = 0)

Cache Statistics