Session client support¶

Default¶

class ninchat.client.Session¶

Actions may be sent via the send() method.

A server session must be established by configuring callbacks, calling the set_params() and open() methods, and waiting for a “session_created” (or an “error”) event. If the server drops the session (due to network timeout or some other exceptional reason), a new server session is created automatically, and another “session_created” event is delivered.

Callbacks (the attributes prefixed with “on”) may either be configured by setting them as properties, or by subclassing Session and implementing them as methods.

Action/event params are dictionaries of string keys and arbitrary values. Action/event payloads are lists of bytes-like objects. See https://ninchat.com/api for details.

Threading:

• The API is not thread-safe. If Session methods are invoked on multiple threads (probably a bad idea), proper synchronization must be taken care of.
• The callbacks are executed on arbitrary threads, so proper synchronization must be taken care of. (The asyncio and gevent implementations avoid this problem.)

on_session_event¶

Session creation/failure callback. Invoked with the event’s params. If an “error” event is delivered, it means that a new server session cannot be created automatically; the set_params() method must be used to update login credentials. The close() method must be called if the session will not be resumed after an error.

on_event¶

Event delivery callback. Invoked with the event’s params, event’s payload, and a boolean which indicates if it was the last reply to the action indicated by the event’s “action_id” parameter.

on_close¶

Indicates that the session closure initiated by calling the close() method has completed. Invoked without arguments.

on_conn_state¶

Indicates a change in the internal connection state. Invoked with one of the strings: “connecting”, “connected”, “disconnected”.

on_active¶

Indicates that there has recently been activity on the connection. Invoked without arguments.

close()¶

Close the session on the server.

open(on_open=None)¶

Create a session on the server. If specified, the on_open callback will be called with the (initial) session creation/failure event’s params.

send(params, payload=None, on_reply=None)¶

Send an action. If specified, the on_reply callback will be invoked with the reply event(s). If the session is closed before the final reply event is received, the callback will be invoked with params set to None.

set_params(params)¶

Sets or replaces the params to be used for the next “create_session” action.

exception ninchat.client.Error¶

Raised by some Session methods.

Gevent interoperability¶

class ninchat.client.gevent.Session¶

A version of ninchat.client.Session which executes callbacks in the main thread’s gevent event loop.

Asyncio support¶

class ninchat.client.asyncio.Session(*, loop=None)¶

A version of ninchat.client.Session which executes callbacks in the asyncio event loop.

opened¶

A future which provides the session_created event’s parameters once the session has been created (for the first time).

closed¶

A future which will be marked as done once the session closing is complete.

call(params, payload=None, on_reply=None)¶

An awaitable version of ninchat.client.Session.send(). Returns the final reply event’s params and payload.

close()¶

Like ninchat.client.Session.close(), but returns a future.

open(on_reply=None)¶

Like ninchat.client.Session.open(), but returns a future. The on_reply callback is supported for interface compatibility.