SocketClient#

Added in version 2.22.

class SocketClient(**properties: Any)#

Superclasses: Object

GSocketClient is a lightweight high-level utility class for connecting to a network host using a connection oriented socket type.

You create a GSocketClient object, set any options you want, and then call a sync or async connect operation, which returns a SocketConnection subclass on success.

The type of the SocketConnection object returned depends on the type of the underlying socket that is in use. For instance, for a TCP/IP connection it will be a TcpConnection.

As GSocketClient is a lightweight object, you don’t need to cache it. You can just create a new one any time you need one.

Constructors#

class SocketClient

classmethod new() → SocketClient#: Creates a new SocketClient with the default options.

Added in version 2.22.

Methods#

class SocketClient

add_application_proxy(protocol: str) → None#

Enable proxy protocols to be handled by the application. When the indicated proxy protocol is returned by the ProxyResolver, SocketClient will consider this protocol as supported but will not try to find a Proxy instance to handle handshaking. The application must check for this case by calling get_remote_address() on the returned SocketConnection, and seeing if it’s a ProxyAddress of the appropriate type, to determine whether or not it needs to handle the proxy handshaking itself.

This should be used for proxy protocols that are dialects of another protocol such as HTTP proxy. It also allows cohabitation of proxy protocols that are reused between protocols. A good example is HTTP. It can be used to proxy HTTP, FTP and Gopher and can also be use as generic socket proxy through the HTTP CONNECT method.

When the proxy is detected as being an application proxy, TLS handshake will be skipped. This is required to let the application do the proxy specific handshake.

Parameters:: protocol – The proxy protocol

connect(connectable: SocketConnectable, cancellable: Cancellable | None = None) → SocketConnection#

Tries to resolve the connectable and make a network connection to it.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

The type of the SocketConnection object returned depends on the type of the underlying socket that is used. For instance, for a TCP/IP connection it will be a TcpConnection.

The socket created will be the same family as the address that the connectable resolves to, unless family is set with set_family() or indirectly via set_local_address(). The socket type defaults to STREAM but can be set with set_socket_type().

If a local address is specified with set_local_address() the socket will be bound to this address before connecting.

Added in version 2.22.

Parameters:

connectable – a SocketConnectable specifying the remote address.
cancellable – optional Cancellable object, None to ignore.

async connect_async(self, connectable: SocketConnectable) → SocketConnection#

This is the awaitable version of connect_async().

Added in version 2.22.

Parameters:: connectable – a SocketConnectable specifying the remote address.

connect_async(connectable: SocketConnectable, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

This is the asynchronous version of connect().

You may wish to prefer the asynchronous version even in synchronous command line programs because, since 2.60, it implements RFC 8305 “Happy Eyeballs” recommendations to work around long connection timeouts in networks where IPv6 is broken by performing an IPv4 connection simultaneously without waiting for IPv6 to time out, which is not supported by the synchronous call. (This is not an API guarantee, and may change in the future.)

When the operation is finished callback will be called. You can then call connect_finish() to get the result of the operation.

Added in version 2.22.

Parameters:

connectable – a SocketConnectable specifying the remote address.
cancellable – a Cancellable, or None
callback – a AsyncReadyCallback
user_data – user data for the callback

connect_finish(result: AsyncResult) → SocketConnection#

Finishes an async connect operation. See connect_async()

Added in version 2.22.

Parameters:: result – a AsyncResult.

connect_to_host(host_and_port: str, default_port: int, cancellable: Cancellable | None = None) → SocketConnection#

This is a helper function for connect().

Attempts to create a TCP connection to the named host.

host_and_port may be in any of a number of recognized formats; an IPv6 address, an IPv4 address, or a domain name (in which case a DNS lookup is performed). Quoting with [] is supported for all address types. A port override may be specified in the usual way with a colon. Ports may be given as decimal numbers or symbolic names (in which case an /etc/services lookup is performed).

If no port override is given in host_and_port then default_port will be used as the port number to connect to.

In general, host_and_port is expected to be provided by the user (allowing them to give the hostname, and a port override if necessary) and default_port is expected to be provided by the application.

In the case that an IP address is given, a single connection attempt is made. In the case that a name is given, multiple connection attempts may be made, in turn and according to the number of address records in DNS, until a connection succeeds.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

Added in version 2.22.

Parameters:

host_and_port – the name and optionally port of the host to connect to
default_port – the default port to connect to
cancellable – a Cancellable, or None

async connect_to_host_async(self, host_and_port: str, default_port: int) → SocketConnection#

This is the awaitable version of connect_to_host_async().

Added in version 2.22.

Parameters:

host_and_port – the name and optionally the port of the host to connect to
default_port – the default port to connect to

connect_to_host_async(host_and_port: str, default_port: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

This is the asynchronous version of connect_to_host().

When the operation is finished callback will be called. You can then call connect_to_host_finish() to get the result of the operation.

Added in version 2.22.

Parameters:

host_and_port – the name and optionally the port of the host to connect to
default_port – the default port to connect to
cancellable – a Cancellable, or None
callback – a AsyncReadyCallback
user_data – user data for the callback

connect_to_host_finish(result: AsyncResult) → SocketConnection#

Finishes an async connect operation. See connect_to_host_async()

Added in version 2.22.

Parameters:: result – a AsyncResult.

connect_to_service(domain: str, service: str, cancellable: Cancellable | None = None) → SocketConnection#

Attempts to create a TCP connection to a service.

This call looks up the SRV record for service at domain for the “tcp” protocol. It then attempts to connect, in turn, to each of the hosts providing the service until either a connection succeeds or there are no hosts remaining.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

Parameters:

domain – a domain name
service – the name of the service to connect to
cancellable – a Cancellable, or None

async connect_to_service_async(self, domain: str, service: str) → SocketConnection#

This is the awaitable version of connect_to_service_async().

Added in version 2.22.

Parameters:

domain – a domain name
service – the name of the service to connect to

connect_to_service_async(domain: str, service: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

This is the asynchronous version of connect_to_service().

Added in version 2.22.

Parameters:

domain – a domain name
service – the name of the service to connect to
cancellable – a Cancellable, or None
callback – a AsyncReadyCallback
user_data – user data for the callback

connect_to_service_finish(result: AsyncResult) → SocketConnection#

Finishes an async connect operation. See connect_to_service_async()

Added in version 2.22.

Parameters:: result – a AsyncResult.

connect_to_uri(uri: str, default_port: int, cancellable: Cancellable | None = None) → SocketConnection#

This is a helper function for connect().

Attempts to create a TCP connection with a network URI.

uri may be any valid URI containing an “authority” (hostname/port) component. If a port is not specified in the URI, default_port will be used. TLS will be negotiated if SocketClient:tls is True. (SocketClient does not know to automatically assume TLS for certain URI schemes.)

Using this rather than connect() or connect_to_host() allows SocketClient to determine when to use application-specific proxy protocols.

Upon a successful connection, a new SocketConnection is constructed and returned. The caller owns this new object and must drop their reference to it when finished with it.

In the event of any failure (DNS error, service not found, no hosts connectable) None is returned and error (if non-None) is set accordingly.

Added in version 2.26.

Parameters:

uri – A network URI
default_port – the default port to connect to
cancellable – a Cancellable, or None

async connect_to_uri_async(self, uri: str, default_port: int) → SocketConnection#

This is the awaitable version of connect_to_uri_async().

Added in version 2.26.

Parameters:

uri – a network uri
default_port – the default port to connect to

connect_to_uri_async(uri: str, default_port: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

This is the asynchronous version of connect_to_uri().

When the operation is finished callback will be called. You can then call connect_to_uri_finish() to get the result of the operation.

Added in version 2.26.

Parameters:

uri – a network uri
default_port – the default port to connect to
cancellable – a Cancellable, or None
callback – a AsyncReadyCallback
user_data – user data for the callback

connect_to_uri_finish(result: AsyncResult) → SocketConnection#

Finishes an async connect operation. See connect_to_uri_async()

Added in version 2.26.

Parameters:: result – a AsyncResult.

do_event(self, event: SocketClientEvent, connectable: SocketConnectable, connection: IOStream) → None#

Parameters:

event
connectable
connection

get_enable_proxy() → bool#: Gets the proxy enable state; see set_enable_proxy()

Added in version 2.26.

get_family() → SocketFamily#

Gets the socket family of the socket client.

See set_family() for details.

Added in version 2.22.

get_local_address() → SocketAddress | None#

Gets the local address of the socket client.

See set_local_address() for details.

Added in version 2.22.

get_protocol() → SocketProtocol#

Gets the protocol name type of the socket client.

See set_protocol() for details.

Added in version 2.22.

get_proxy_resolver() → ProxyResolver#: Gets the ProxyResolver being used by client. Normally, this will be the resolver returned by get_default(), but you can override it with set_proxy_resolver().

Added in version 2.36.

get_socket_type() → SocketType#

Gets the socket type of the socket client.

See set_socket_type() for details.

Added in version 2.22.

get_timeout() → int#

Gets the I/O timeout time for sockets created by client.

See set_timeout() for details.

Added in version 2.26.

get_tls() → bool#: Gets whether client creates TLS connections. See set_tls() for details.

Added in version 2.28.

get_tls_validation_flags() → TlsCertificateFlags#

Gets the TLS validation flags used creating TLS connections via client.

This function does not work as originally designed and is impossible to use correctly. See SocketClient:tls-validation-flags for more information.

Added in version 2.28.

Deprecated since version 2.72: Do not attempt to ignore validation errors.

set_enable_proxy(enable: bool) → None#

Sets whether or not client attempts to make connections via a proxy server. When enabled (the default), SocketClient will use a ProxyResolver to determine if a proxy protocol such as SOCKS is needed, and automatically do the necessary proxy negotiation.

Properties#

class SocketClient

props.enable_proxy: bool#: The type of the None singleton.

Added in version 2.22.

props.family: SocketFamily#: The type of the None singleton.

Added in version 2.22.

props.local_address: SocketAddress#: The type of the None singleton.

Added in version 2.22.

props.protocol: SocketProtocol#: The type of the None singleton.

Added in version 2.22.

props.proxy_resolver: ProxyResolver#: The type of the None singleton.

Added in version 2.36.

props.timeout: int#: The type of the None singleton.

Added in version 2.22.

props.tls: bool#: The type of the None singleton.

Added in version 2.22.

props.tls_validation_flags: TlsCertificateFlags#: The type of the None singleton.

Deprecated since version 2.72: Do not attempt to ignore validation errors.

props.type: SocketType#: The type of the None singleton.

Added in version 2.22.

Signals#

class SocketClient.signals

event(event: SocketClientEvent, connectable: SocketConnectable, connection: IOStream | None = None) → None#

The type of the None singleton.

Added in version 2.32.

Parameters:

event – the event that is occurring
connectable – the SocketConnectable that event is occurring on
connection – the current representation of the connection

Virtual Methods#

class SocketClient

do_event(event: SocketClientEvent, connectable: SocketConnectable, connection: IOStream) → None#

The type of the None singleton.

Parameters:

event
connectable
connection

Fields#

class SocketClient

parent_instance#

priv#

SocketClient#

Constructors#

Methods#

Properties#

Signals#

Virtual Methods#

Fields#

This Page