API Reference#

Session#

class requests_doh.DNSOverHTTPSSession(*args, **kwargs)#

A ready-to-use DoH (DNS-over-HTTPS) requests.Session

Parameters:

provider (str) – A DoH provider
cache_expire_time (float) – Set DNS cache expire time

Adapters#

class requests_doh.DNSOverHTTPSAdapter(provider=None, cache_expire_time=None, **kwargs)#

An DoH (DNS over HTTPS) adapter for requests.Session

Parameters:

provider (str) – A DoH provider
cache_expire_time (float) – Set DNS cache expire time
**kwargs – These parameters will be passed to requests.adapters.HTTPAdapter

DNS resolver session#

requests_doh.set_resolver_session(session)#

Set http session to resolve DNS

Parameters:: session (requests.Session) – An http session to resolve DNS
Raises:: ValueError – session parameter is not requests.Session instance

requests_doh.get_resolver_session()#

Returns:: Return an http session for DoH resolver
Return type:: requests.Session

DoH (DNS-over-HTTPS) Provider#

requests_doh.add_dns_provider(name, address, switch=False)#

Add a DoH provider

Parameters:

name (str) – Name for DoH provider
address (str) – Full URL / endpoint for DoH provider
switch (Optional[bool]) – If True, the DoH provider will automatically switch to newly created DoH provider

requests_doh.remove_dns_provider(name, fallback=None)#

Remove a DoH provider

If parameter name is an active DoH provider, get_dns_provider() will return None. You must set fallback parameter to one of available DoH providers (fallback and name parameters cannot be same value) or you can call set_dns_provider() after calling this function in order to get DoH working

For example:

from requests_doh import DNSOverHTTPSSession, add_dns_provider, remove_dns_provider

# Add a custom DNS and set it to active
add_dns_provider("another-dns", "https://another-dns.example.com/dns-query", switch=True)

# At this point, the session is still working
session = DNSOverHTTPSSession("another-dns")
r = session.get("https://example.com")
print(r.status_code)

# Let's try to remove the newly created DNS
remove_dns_provider("another-dns", fallback="cloudflare")

# Or we can call `set_dns_provider()`
# if we didn't set `fallback` parameter
# set_dns_provider("cloudflare")

# At this point DoH provider "another-dns" is removed
# and "cloudflare" is set to active DoH provider
# the session is still working
r = session.get("https://google.com")

But what will happend if we didn’t add fallback parameter or didn’t call set_dns_provider() ? Well error will occurred, take a look at this example:

from requests_doh import DNSOverHTTPSSession, add_dns_provider, remove_dns_provider

# Add a custom DNS and set it to active
add_dns_provider("another-dns", "https://another-dns.example.com/dns-query", switch=True)

# At this point, the session is still working
session = DNSOverHTTPSSession("another-dns")
r = session.get("https://example.com")
print(r.status_code)

# Let's try to remove the newly created DNS
remove_dns_provider("another-dns")

# If we send request to this URL, it would still working
r = session.get("https://example.com")
print(r.status_code)

# An error occurred when we send to another URL
# Because we didn't set ``falback`` parameter in `remove_dns_provider()`
# (or calling function `set_dns_provider()`)
# `get_dns_provider()` will return ``None`` and thus resolving DNS will be failed
# Because there is no valid endpoint where we wanna resolve DNS of the host
r = session.get("https://google.com")

Parameters:

name (str) – DoH provider that want to remove
fallback (str) – Set a fallback DoH provider

Raises:

DoHProviderNotExist – DoH provider is not exist in list of available DoH providers

requests_doh.set_dns_provider(provider)#

Set a DoH provider, must be a valid DoH providers

Parameters:: provider (str) – An valid DoH provider, see DoH (DNS-over-HTTPS) providers
Raises:: DoHProviderNotExist – Invalid DoH provider

requests_doh.get_dns_provider()#

Returns:: Return current DoH provider
Return type:: str

requests_doh.get_all_dns_provider()#

Returns:: Return all available DoH providers
Return type:: tuple[str]

DNS Cache#

requests_doh.set_dns_cache_expire_time(time)#

Set DNS cache expired time in seconds

Parameters:: time (float) – An expire time

requests_doh.purge_dns_cache(host=None)#

Purge DNS cache

Parameters:: host (str) – Cached DNS host want to be purged, if host is None, all DNS caches will be purged.

Exceptions#

exception requests_doh.RequestsDOHException#: Base exception for requests_doh library

exception requests_doh.DNSQueryFailed#: Failed to query DNS from given host

exception requests_doh.DoHProviderNotExist#: DoH provider is not exist in list of available DoH providers