Package legume :: Module client :: Class Client

Class Client

               object --+    
                        |    
netshared.NetworkEndpoint --+
                            |
               object --+   |
                        |   |
          metrics.Metrics --+
                            |
                           Client

A `Client` manages the connection to a `Server` instance elsewhere.

Creating an instance of a `Client` and connecting to a server is done
as shown in the minimalist example below::

    client = Client()
    # Server is running on localhost port 9000
    client.connect(('localhost', 9000))

    # This loop ensures that .update() is called.
    while True:
        client.update()
        # Add a small time delay to prevent pegging the CPU.
        time.sleep(0.0001)

The `Client` has a number of events that can be hooked into that provide
notifications of data sent from the server and state changes. An event
consists of the sender and the argument(in the example below, this
is the message), eg::

    def my_message_handler(sender, message):
        print "The greeting reads: %s" % message.greeting.value

    my_client.OnMessage += my_message_handler

For the `Client.OnMessage` handler example above the argument part of the
event received is a re-assembled instance of the message that was sent, and
the greeting field in the message is obtained via
the fields `value` attribute.

* `Client.OnConnectRequestAccepted` - Fired when a `Client.connect` request
    has been responded to by the server allowing the connection.
* `Client.OnConnectRequestRejected` - Fired when a `Client.connect` request
    has been responded to by the server deneying the connection.
* `Client.OnMessage` - Fired when a message is receieved from the server.
    See above example.
* `Client.OnError` - An error has occured. The event argument is a string
    detailing the error.
* `Client.OnDisconnect` - The connection was gracefully closed by the
    Server. If the connection was severed due to a time-out, the
    `Client.OnError` event would fire.

Instance Methods

__init__(self, message_factory=messages.message_factory)
Create a Client endpoint.

connect(self, address)
Initiate a connection to the server at the specified address.

disconnect(self)
Gracefully disconnect from the host.

send_message(self, message)
Send a message to the server.

send_reliable_message(self, message)
Send a message to the server with guaranteed delivery.

update(self)
This method should be called frequently to process incoming data, send outgoing data, and raise events.

__del__(self) (Inherited from legume.netshared.NetworkEndpoint)

do_read(self, callback) (Inherited from legume.netshared.NetworkEndpoint)

get_state(self) (Inherited from legume.netshared.NetworkEndpoint)

is_active(self) (Inherited from legume.netshared.NetworkEndpoint)

setTimeout(self, timeout) (Inherited from legume.netshared.NetworkEndpoint)

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Variables
	CONNECTED = `104` (Inherited from legume.netshared.NetworkEndpoint)
	CONNECTING = `103` (Inherited from legume.netshared.NetworkEndpoint)
	DISCONNECTED = `100` (Inherited from legume.netshared.NetworkEndpoint)
	ERRORED = `101` (Inherited from legume.netshared.NetworkEndpoint)
	LISTENING = `102` (Inherited from legume.netshared.NetworkEndpoint)
	MTU = `1400` (Inherited from legume.netshared.NetworkEndpoint)

Properties
	connected Returns True if this endpoint's state is `CONNECTED`.
	disconnected Returns True if this endpoint's state is `DISCONNECTED`.
	errored Returns True if this endpoint's state is `ERRORED`.
	is_server Returns false.
	latency Round-trip latency in ms
	out_buffer_bytes Count of bytes waiting to be transmitted on the wire.
	pending_acks Packets that have not yet been acknowledged.
	in_bytes Count of bytes received (header + data).
	out_bytes Count of bytes recieved (header + data).
	in_packets Count of packets received.
	out_packets Count of packets sent.
	keepalive_count Count of keep-alive Ping or Pong messages sent/received.
	reorder_queue Number of out-of-order messages received that are waiting to be inserted into the message stream.
	OnConnectRequestRejected
	OnMessage
	OnConnectRequestAccepted
	OnError
	OnDisconnect
	in_messages Count of messages received. (Inherited from legume.metrics.Metrics)
	out_messages Count of messages sent. (Inherited from legume.metrics.Metrics)
	socket (Inherited from legume.netshared.NetworkEndpoint)
	state (Inherited from legume.netshared.NetworkEndpoint)
	timeout (Inherited from legume.netshared.NetworkEndpoint)
Inherited from `object`: `__class__`

Method Details

init(self, message_factory=messages.message_factory)
(Constructor)


Create a Client endpoint. A Client is initially in the closed state
until a call to `connect`.

A messages factory is required to assemble and disassemble messages for
pushing down the intertubes to the server endpoint. If a
message_factory is not explicitly specified then the global
message_factory will be used.

:Parameters:
    message_factory : `MessageFactory`
        A message factory.

Overrides: object.__init__

connect(self, address)


Initiate a connection to the server at the specified address.

This method will put the socket into the `CONNECTING` state. If a
connection is already established a ClientError exception is raised.

:Parameters:
    address : (host, port)
        Host address. An ArgumentError exception will be raised for
        an invalid address.

disconnect(self)


Gracefully disconnect from the host. A disconnection packet is
sent to the server upon calling the .update() method. The connection
status of the class instance will not changed to  `DISCONNECTED`
until .update() is called.

send_message(self, message)


Send a message to the server. The message is added to the output buffer.
To flush the output buffer call the .update() method. If the client
is not connected to the server a `ClientError` exception is raised.

:Parameters:
    message : `BaseMessage`
        The message to be sent

send_reliable_message(self, message)


Send a message to the server with guaranteed delivery. If the
client is not connected to the server a `ClientError` exception
is raised.

:Parameters:
    message : `BaseMessage`
        The message to be sent

Property Details

connected


Returns True if this endpoint's state is `CONNECTED`.

Get Method:: unreachable.connected(self) - Returns True if this endpoint's state is `CONNECTED`.

disconnected


Returns True if this endpoint's state is `DISCONNECTED`.

Get Method:: unreachable.disconnected(self) - Returns True if this endpoint's state is `DISCONNECTED`.

errored


Returns True if this endpoint's state is `ERRORED`.

Get Method:: unreachable.errored(self) - Returns True if this endpoint's state is `ERRORED`.

is_server

Returns false.

Get Method:: unreachable.is_server(self) - Returns false.

latency

Round-trip latency in ms

Get Method:: unreachable.latency(self)

out_buffer_bytes

Count of bytes waiting to be transmitted on the wire.

Get Method:: unreachable.out_buffer_bytes(self)

pending_acks

Packets that have not yet been acknowledged.

Get Method:: unreachable.pending_acks(self)

in_bytes

Count of bytes received (header + data).

Get Method:: unreachable.in_bytes(self)

out_bytes

Count of bytes recieved (header + data).

Get Method:: unreachable.out_bytes(self)

in_packets

Count of packets received.

Get Method:: unreachable.in_packets(self)

out_packets

Count of packets sent.

Get Method:: unreachable.out_packets(self)

keepalive_count

Count of keep-alive Ping or Pong messages sent/received.

Get Method:: unreachable.keepalive_count(self)

reorder_queue

Number of out-of-order messages received that are waiting to be
inserted into the message stream.

Get Method:: unreachable.reorder_queue(self)

OnConnectRequestRejected

Get Method:: _getOnConnectRequestRejected(self)
Set Method:: _setOnConnectRequestRejected(self, event)

OnMessage

Get Method:: _getOnMessage(self)
Set Method:: _setOnMessage(self, event)

OnConnectRequestAccepted

Get Method:: _getOnConnectRequestAccepted(self)
Set Method:: _setOnConnectRequestAccepted(self, event)

OnError

Get Method:: _getOnError(self)
Set Method:: _setOnError(self, event)

OnDisconnect

Get Method:: _getOnDisconnect(self)
Set Method:: _setOnDisconnect(self, event)