twisted.application.internet.ClientService

class documentation

class ClientService(service.Service): (source)

Constructor: ClientService(endpoint, factory, retryPolicy, clock, prepareConnection)

A ClientService maintains a single outgoing connection to a client endpoint, reconnecting after a configurable timeout when a connection fails, either before or after connecting.

Present Since
16.1.0

Method	`__init__`	No summary
Method	`startService`	Start this `ClientService`, initiating the connection retry loop.
Method	`stopService`	Stop attempting to reconnect and close any existing connections.
Method	`whenConnected`	Retrieve the currently-connected `Protocol`, or the next one to connect.
Class Variable	`_log`	Undocumented
Instance Variable	`_machine`	Undocumented

Inherited from Service:

Method	`__getstate__`	Undocumented
Method	`disownServiceParent`	Use this API to remove an `IService` from an `IServiceCollection`.
Method	`privilegedStartService`	Do preparation work for starting the service.
Method	`setName`	Set the name of the service.
Method	`setServiceParent`	Set the parent of the service. This method is responsible for setting the `parent` attribute on this service (the child service).
Instance Variable	`name`	A `str` which is the name of the service or `None`.
Instance Variable	`parent`	An `IServiceCollection` which is the parent or `None`.
Instance Variable	`running`	A `boolean` which indicates whether the service is running.

def __init__(self, endpoint, factory, retryPolicy=None, clock=None, prepareConnection=None): (source) ¶

Parameters
endpoint	A `stream client endpoint` provider which will be used to connect when the service starts.
factory	A `protocol factory` which will be used to create clients for the endpoint.
retryPolicy:callable taking (the number of failed connection attempts made in a row (`int`)) and returning the number of seconds to wait before making another attempt.	A policy configuring how long `ClientService` will wait between attempts to connect to `endpoint`.
clock:`IReactorTime`	The clock used to schedule reconnection. It's mainly useful to be parametrized in tests. If the factory is serialized, this attribute will not be serialized, and the default value (the reactor) will be restored when deserialized.
prepareConnection:`callable`	A single argument `callable` that may return a `Deferred`. It will be called once with the `protocol` each time a new connection is made. It may call methods on the protocol to prepare it for use (e.g. authenticate) or validate it (check its health). The `prepareConnection` callable may raise an exception or return a `Deferred` which fails to reject the connection. A rejected connection is not used to fire an `Deferred` returned by `whenConnected`. Instead, `ClientService` handles the failure and continues as if the connection attempt were a failure (incrementing the counter passed to `retryPolicy`). `Deferred`s returned by `whenConnected` will not fire until any `Deferred` returned by the `prepareConnection` callable fire. Otherwise its successful return value is consumed, but ignored. Present Since Twisted 18.7.0

def startService(self): (source) ¶

from twisted.application.service.IService

overrides twisted.application.service.Service.startService

Start this ClientService, initiating the connection retry loop.

def stopService(self): (source) ¶

from twisted.application.service.IService

overrides twisted.application.service.Service.stopService

Stop attempting to reconnect and close any existing connections.

Returns
a `Deferred` that fires when all outstanding connections are closed and all in-progress connection attempts halted.

def whenConnected(self, failAfterFailures=None): (source) ¶

Retrieve the currently-connected Protocol, or the next one to connect.

Parameters
failAfterFailures:`int` or None	number of connection failures after which the Deferred will deliver a Failure (None means the Deferred will only fail if/when the service is stopped). Set this to 1 to make the very first connection failure signal an error. Use 2 to allow one failure but signal an error if the subsequent retry then fails.
Returns
`Deferred` that may: fire with `IProtocol` fail with `CancelledError` when the service is stopped fail with e.g. `DNSLookupError` or `ConnectionRefusedError` when the number of consecutive failed connection attempts equals the value of "failAfterFailures"	a Deferred that fires with a protocol produced by the factory passed to `__init__`

_log = (source) ¶

Undocumented

_machine = (source) ¶

Undocumented