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[source]
get_statistics_snapshot()[source]

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()[source]

How many hits has the cache had?

misses()[source]

How many misses has the cache had?

reset_statistics()[source]

Reset all statistics to zero.

class dns.resolver.Cache(cleaning_interval=300.0)[source]

Simple thread-safe DNS answer cache.

cleaning_interval, a float is the number of seconds between periodic cleanings.

flush(key=None)[source]

Flush the cache.

If key is not None, only that item is flushed. Otherwise the entire cache is flushed.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

get(key)[source]

Get the answer associated with key.

Returns None if no answer is cached for the key.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

Returns a dns.resolver.Answer or None.

put(key, value)[source]

Associate key and value in the cache.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

value, a dns.resolver.Answer, the answer.

class dns.resolver.LRUCache(max_size=100000)[source]

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.

max_size, an int, is the maximum number of nodes to cache; it must be greater than 0.

flush(key=None)[source]

Flush the cache.

If key is not None, only that item is flushed. Otherwise the entire cache is flushed.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

get(key)[source]

Get the answer associated with key.

Returns None if no answer is cached for the key.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

Returns a dns.resolver.Answer or None.

get_hits_for_key(key)[source]

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

put(key, value)[source]

Associate key and value in the cache.

key, a (dns.name.Name, int, int) tuple whose values are the query name, rdtype, and rdclass respectively.

value, a dns.resolver.Answer, the answer.

class dns.resolver.CacheStatistics(hits=0, misses=0)[source]

Cache Statistics