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:

DNS resolver session

requests_doh.set_resolver_session(session)

Set http session to resolve DNS

Parameters:

session (httpx.Client) – An http session to resolve DNS

Raises:

ValueError – session parameter is not httpx.Client instance

requests_doh.get_resolver_session()
Returns:

Return an http session for DoH resolver

Return type:

httpx.Client

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 same 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