DNS Resolver

class urllib3.contrib.resolver.BaseResolver(server, port=None, *patterns, **kwargs)

Bases: object

Parameters:

  • server (str | None)

  • port (int | None)

  • patterns (str)

  • kwargs (Any)

abstract close()

Terminate the given resolver instance. This should render it unusable. Further inquiries should raise an exception.

Return type:

None

create_connection(address, timeout=_TYPE_DEFAULT.token, source_address=None, socket_options=None, socket_kind=SocketKind.SOCK_STREAM, *, quic_upgrade_via_dns_rr=False, timing_hook=None, default_socket_family=AddressFamily.AF_UNSPEC)

Connect to address and return the socket object.

Convenience function. Connect to address (a 2-tuple (host, port)) and return the socket object. Passing the optional timeout parameter will set the timeout on the socket instance before attempting to connect. If no timeout is supplied, the global default timeout setting returned by socket.getdefaulttimeout() is used. If source_address is set it must be a tuple of (host, port) for the socket to bind as a source address before making the connection. An host of ‘’ or port 0 tells the OS to use the default.

Parameters:
Return type:

socket

abstract getaddrinfo(host, port, family, type, proto=0, flags=0, *, quic_upgrade_via_dns_rr=False)

This method align itself on the standard library socket.getaddrinfo(). It must be implemented as-is on your Resolver.

Parameters:

  • host (bytes | str | None)

  • port (str | int | None)

  • family (AddressFamily)

  • type (SocketKind)

  • proto (int)

  • flags (int)

  • quic_upgrade_via_dns_rr (bool)

Return type:

list[tuple[AddressFamily, SocketKind, int, str, tuple[str, int] | tuple[str, int, int, int]]]

have_constraints()
Return type:

bool

implementation: ClassVar[str]
abstract is_available()

Determine if Resolver can receive inquiries.

Return type:

bool

property port: int | None
protocol: ClassVar[ProtocolResolver]
recycle()
Return type:

BaseResolver

property server: str | None
specifier: ClassVar[str | None] = None
support(hostname)

Determine if given hostname is especially resolvable by given resolver. If this resolver does not have any constrained list of host, it returns None. Meaning it support any hostname for resolution.

Parameters:

hostname (str | bytes | None)

Return type:

bool | None

class urllib3.contrib.resolver.ManyResolver(*resolvers)

Bases: BaseResolver

Special resolver that use many child resolver. Priorities are based on given order (list of BaseResolver).

Parameters:

resolvers (BaseResolver)

close()

Terminate the given resolver instance. This should render it unusable. Further inquiries should raise an exception.

Return type:

None

getaddrinfo(host, port, family, type, proto=0, flags=0, *, quic_upgrade_via_dns_rr=False)

This method align itself on the standard library socket.getaddrinfo(). It must be implemented as-is on your Resolver.

Parameters:

  • host (bytes | str | None)

  • port (str | int | None)

  • family (AddressFamily)

  • type (SocketKind)

  • proto (int)

  • flags (int)

  • quic_upgrade_via_dns_rr (bool)

Return type:

list[tuple[AddressFamily, SocketKind, int, str, tuple[str, int] | tuple[str, int, int, int]]]

is_available()

Determine if Resolver can receive inquiries.

Return type:

bool

recycle()
Return type:

BaseResolver

class urllib3.contrib.resolver.ProtocolResolver(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

At urllib3.future we aim to propose a wide range of DNS-protocols. The most used techniques are available.

CUSTOM = 'custom'

Custom (e.g. your own implementation, use this when it does not suit any of the protocols specified)

DOH = 'doh'

DNS over HTTPS

DOQ = 'doq'

DNS over QUIC

DOT = 'dot'

DNS over TLS

DOU = 'dou'

DNS over UDP (insecure)

MANUAL = 'in-memory'

Manual (e.g. hosts)

NULL = 'null'

Void (e.g. purposely disable resolution)

SYSTEM = 'system'

Ask the OS native DNS layer

class urllib3.contrib.resolver.ResolverDescription(protocol, specifier=None, implementation=None, server=None, port=None, *host_patterns, **kwargs)

Bases: object

Describe how a BaseResolver must be instantiated.

Parameters:
static from_url(url)
Parameters:

url (str)

Return type:

ResolverDescription

new()
Return type:

BaseResolver

class urllib3.contrib.resolver.ResolverFactory

Bases: object

static has(protocol, specifier=None, implementation=None)
Parameters:
Return type:

bool

static new(protocol, specifier=None, implementation=None, **kwargs)
Parameters:
Return type:

BaseResolver

class urllib3.contrib.resolver._async.AsyncBaseResolver(server, port=None, *patterns, **kwargs)

Bases: BaseResolver

Parameters:

  • server (str | None)

  • port (int | None)

  • patterns (str)

  • kwargs (Any)

abstract async close()

Terminate the given resolver instance. This should render it unusable. Further inquiries should raise an exception.

Return type:

None

async create_connection(address, timeout=_TYPE_DEFAULT.token, source_address=None, socket_options=None, socket_kind=SocketKind.SOCK_STREAM, *, quic_upgrade_via_dns_rr=False, timing_hook=None, default_socket_family=AddressFamily.AF_UNSPEC)

Connect to address and return the socket object.

Convenience function. Connect to address (a 2-tuple (host, port)) and return the socket object. Passing the optional timeout parameter will set the timeout on the socket instance before attempting to connect. If no timeout is supplied, the global default timeout setting returned by socket.getdefaulttimeout() is used. If source_address is set it must be a tuple of (host, port) for the socket to bind as a source address before making the connection. An host of ‘’ or port 0 tells the OS to use the default.

Parameters:
Return type:

AsyncSocket

abstract async getaddrinfo(host, port, family, type, proto=0, flags=0, *, quic_upgrade_via_dns_rr=False)

This method align itself on the standard library socket.getaddrinfo(). It must be implemented as-is on your Resolver.

Parameters:

  • host (bytes | str | None)

  • port (str | int | None)

  • family (AddressFamily)

  • type (SocketKind)

  • proto (int)

  • flags (int)

  • quic_upgrade_via_dns_rr (bool)

Return type:

list[tuple[AddressFamily, SocketKind, int, str, tuple[str, int] | tuple[str, int, int, int]]]

recycle()
Return type:

AsyncBaseResolver

class urllib3.contrib.resolver._async.AsyncManyResolver(*resolvers)

Bases: AsyncBaseResolver

Special resolver that use many child resolver. Priorities are based on given order (list of BaseResolver).

Parameters:

resolvers (AsyncBaseResolver)

async close()

Terminate the given resolver instance. This should render it unusable. Further inquiries should raise an exception.

Return type:

None

async getaddrinfo(host, port, family, type, proto=0, flags=0, *, quic_upgrade_via_dns_rr=False)

This method align itself on the standard library socket.getaddrinfo(). It must be implemented as-is on your Resolver.

Parameters:

  • host (bytes | str | None)

  • port (str | int | None)

  • family (AddressFamily)

  • type (SocketKind)

  • proto (int)

  • flags (int)

  • quic_upgrade_via_dns_rr (bool)

Return type:

list[tuple[AddressFamily, SocketKind, int, str, tuple[str, int] | tuple[str, int, int, int]]]

is_available()

Determine if Resolver can receive inquiries.

Return type:

bool

recycle()
Return type:

AsyncBaseResolver

class urllib3.contrib.resolver._async.AsyncResolverDescription(protocol, specifier=None, implementation=None, server=None, port=None, *host_patterns, **kwargs)

Bases: ResolverDescription

Describe how a BaseResolver must be instantiated.

Parameters:
static from_url(url)
Parameters:

url (str)

Return type:

AsyncResolverDescription

new()
Return type:

AsyncBaseResolver

class urllib3.contrib.resolver._async.AsyncResolverFactory

Bases: object

static has(protocol, specifier=None, implementation=None)
Parameters:
Return type:

bool

static new(protocol, specifier=None, implementation=None, **kwargs)
Parameters:
Return type:

AsyncBaseResolver