Go to the latest version of this document.

# ``twisted`.`internet`.`endpoints`.`HostnameEndpoint``

class documentation

`class HostnameEndpoint: (source)`

Constructor: `HostnameEndpoint(reactor, host, port, timeout, ...)`

Implements interfaces: `twisted.internet.interfaces.IStreamClientEndpoint`

View In Hierarchy

A name-based endpoint that connects to the fastest amongst the resolved host addresses.

Method | `__init__` | Create a `HostnameEndpoint`.
Method | `__repr__` | Produce a string representation of the `HostnameEndpoint`.
Method | `connect` | Attempts a connection to each resolved address, and returns a connection which is established first.
Static Method | `_hostAsBytesAndText` | For various reasons (documented in the `@ivar`'s in the class docstring) we need both a textual and a binary representation of the hostname given to the constructor. For compatibility and convenience, we accept both textual and binary representations of the hostname, save the form that was passed, and convert into the other form...
Method | `_fallbackNameResolution` | Resolve the hostname string into a tuple containing the host address. This is method is only used when the reactor does not provide `IReactorPluggableNameResolver`.
Method | `_getNameResolverAndMaybeWarn` | Retrieve a `nameResolver` callable and warn the caller's caller that using a reactor which doesn't provide `IReactorPluggableNameResolver` is deprecated.
Constant | `_DEFAULT_ATTEMPT_DELAY` | The default time to use between attempts, in seconds, when no `attemptDelay` is given to `HostnameEndpoint.__init__`.
Class Variable | `_deferToThread` | Undocumented
Class Variable | `_getaddrinfo` | Undocumented
Instance Variable | `_attemptDelay` | Undocumented
Instance Variable | `_badHostname` | a flag - hopefully false! - indicating that an invalid hostname was passed to the constructor. This might be a textual hostname that isn't valid IDNA, or non-ASCII bytes.
Instance Variable | `_bindAddress` | Undocumented
Instance Variable | `_hostBytes` | the encoded bytes-representation of the hostname passed to the constructor. Used to construct the `HostnameAddress` associated with this endpoint.
Instance Variable | `_hostText` | the textual representation of the hostname passed to the constructor. Used to pass to the reactor's hostname resolver.
Instance Variable | `_port` | Undocumented
Instance Variable | `_reactor` | Undocumented
Instance Variable | `_timeout` | Undocumented

def __init__(self, reactor: `Any`, host: `str | bytes`, port: `int`, timeout: `float` = 30, bindAddress: `bytes | str | tuple[bytes | str, int] | None` = None, attemptDelay: `float | None` = None): (source)

Create a `HostnameEndpoint`.

Parameters
reactor:provider of `IReactorTCP`, `IReactorTime` and either `IReactorPluggableNameResolver` or `IReactorPluggableResolver`. | The reactor to use for connections and delayed calls.
host:`bytes` or `str` | A hostname to connect to.
port:`int` | The port number to connect to.
timeout:`float` or `int` | For each individual connection attempt, the number of seconds to wait before assuming the connection has failed.

bindAddress:`str`, `tuple`, or None

The client socket normally uses whatever local interface (eth0, en0, lo, etc) is best suited for the target address, and a randomly-assigned port. This argument allows that local address/port to be overridden. Providing just an address (as a str) will bind the client socket to whichever interface is assigned that address. Providing a tuple of (str, int) will bind it to both an interface and a specific local port. To bind the port, but leave the interface unbound, use a tuple of ("", port), or ("0.0.0.0", port) for IPv4, or ("::0", port) for IPv6. To leave both interface and port unbound, just use None.

attemptDelay:`float` | The number of seconds to delay between connection attempts.

See Also
`twisted.internet.interfaces.IReactorTCP.connectTCP`

def __repr__(self) -> `str`: (source)

Produce a string representation of the `HostnameEndpoint`.

Returns
`str` | A `str`

def connect(self, protocolFactory: `IProtocolFactory`) -> `Deferred[IProtocol]`: (source)
from `twisted.internet.interfaces.IStreamClientEndpoint`

Attempts a connection to each resolved address, and returns a connection which is established first.

Parameters
protocolFactory:`IProtocolFactory` | The protocol factory whose protocol will be connected.

Returns
`Deferred[IProtocol]` | A `Deferred` that fires with the connected protocol or fails a connection-related error.

@staticmethod
def _hostAsBytesAndText(host: `bytes | str`) -> `tuple[bool, bytes, str]`: (source)

For various reasons (documented in the `@ivar`'s in the class docstring) we need both a textual and a binary representation of the hostname given to the constructor. For compatibility and convenience, we accept both textual and binary representations of the hostname, save the form that was passed, and convert into the other form. This is mostly just because `HostnameAddress` chose somewhat poorly to define its attribute as bytes; hopefully we can find a compatible way to clean this up in the future and just operate in terms of text internally.

Parameters
host:`bytes | str` | A hostname to convert.

Returns
`tuple[bool, bytes, str]` | a 3-tuple of `(invalid, bytes, text)` where `invalid` is a boolean indicating the validity of the hostname, `bytes` is a binary representation of `host`, and `text` is a textual representation of `host`.

def _fallbackNameResolution(self, host, port): (source)

Resolve the hostname string into a tuple containing the host address. This is method is only used when the reactor does not provide `IReactorPluggableNameResolver`.

Parameters
host | A unicode hostname to resolve.
port | The port to include in the resolution.

Returns
A `Deferred` that fires with `_getaddrinfo`'s return value.

def _getNameResolverAndMaybeWarn(self, reactor: `object`) -> `IHostnameResolver`: (source)

Retrieve a `nameResolver` callable and warn the caller's caller that using a reactor which doesn't provide `IReactorPluggableNameResolver` is deprecated.

Parameters
reactor:`object` | The reactor to check.

Returns
`IHostnameResolver` | A `IHostnameResolver` provider.

_DEFAULT_ATTEMPT_DELAY: `float` = (source)

The default time to use between attempts, in seconds, when no `attemptDelay` is given to `HostnameEndpoint.__init__`.

Value

    0.3

_deferToThread: `ClassVar[_DeferToThreadFunction]` = (source)

Undocumented

_getaddrinfo = (source)

Undocumented

_attemptDelay = (source)

Undocumented

_badHostname: `bool` = (source)

a flag - hopefully false! - indicating that an invalid hostname was passed to the constructor. This might be a textual hostname that isn't valid IDNA, or non-ASCII bytes.

_bindAddress = (source)

Undocumented

_hostBytes: `bytes` = (source)

the encoded bytes-representation of the hostname passed to the constructor. Used to construct the `HostnameAddress` associated with this endpoint.

_hostText: `unicode` = (source)

the textual representation of the hostname passed to the constructor. Used to pass to the reactor's hostname resolver.

_port = (source)

Undocumented

_reactor = (source)

Undocumented

_timeout = (source)

Undocumented