Reference

NGI Application Interfaces

The application interfaces are implemented by application developers to provide application-specific logic. The core application interface is IConnectionHandler:

class zc.ngi.interfaces.IConnectionHandler

Application objects that can handle connection input-data events

This is an application interface.

The methods defined be this interface will never be called simultaneously from separate threads, so implementation of the methods needn’t be concerned with thread safety with respect to these methods.

handle_close(connection, reason)

Receive notification that a connection has closed

The reason argument can be converted to a string for logging purposes. It may have data useful for debugging, but this is undefined.

Notifications are received when the connection is closed externally, for example, when the other side of the connection is closed or in case of a network failure. No notification is given when the connection’s close method is called.

handle_exception(connection, exception)

Recieve a report of an exception encountered by a connection

This method is used to recieve exceptions from an NGI implementation. This will only be due to an error encounted processing data passed to the connection writelines methods.

handle_input(connection, data)

Handle input data from a connection

The data is an 8-bit string.

Note that there are no promises about data organization. The data isn’t necessarily record oriented. For example, data could, in theory be passed one character at a time. It is up to applications to organize data into records, if desired.

class zc.ngi.interfaces.IClientConnectHandler

Receive notifications of connection results

This is an application interface.

connected(connection)

Receive notification that a connection had been established

failed_connect(reason)

Receive notification that a connection could not be established

The reason argument can be converted to a string for logging purposes. It may have data useful for debugging, but this is undefined.

class zc.ngi.interfaces.IServer

Handle server connections

This is an application interface.

A server is just a callable that takes a connection and set’s it’s handler.

class zc.ngi.interfaces.IUDPHandler

Handle udp messages

This is an application interface.

A UDP handler is a callable that takes a client address and an 8-bit string message.

NGI Implementation Interfaces

Implementation interfaces are provided by an implementation and used by applications.

class zc.ngi.interfaces.IConnection

Network connections

This is an implementation interface.

Network connections support communication over a network connection, or any connection having separate input and output channels.

close()

Close the connection

This method is thread safe. It may be called by any thread at any time.

set_handler(handler)

Set the IConnectionHandler for a connection.

This method may be called multiple times, but it should only be called in direct response to an implementation call to a IConnectionHandler, IClientConnectHandler, or IServer.

Any failure of a handler call must be caught and logged. If an exception is raised by a call to hande_input or handle_exception, the connection must be closed by the implementation.

write(data)

Output a string to the connection.

The write call is non-blocking.

This method is thread safe. It may be called by any thread at any time.

writelines(data)

Output an iterable of strings to the connection.

The writelines call is non-blocking. Note, that the data may not have been consumed when the method returns.

This method is thread safe. It may be called by any thread at any time.

class zc.ngi.interfaces.IImplementation

Standard interface for ngi implementations

connect(address, handler)

Try to make a connection to the given address

The handler is an IClientConnectHandler. The handler connected method will be called with an IConnection object if and when the connection succeeds or failed_connect method will be called if the connection fails.

This method is thread safe. It may be called by any thread at any time.

listener(address, handler)

Listen for incoming TCP connections

When a connection is received, call the handler.

An IListener object is returned.

This method is thread safe. It may be called by any thread at any time.

udp(address, message)

Send a UDP message

This method is thread safe. It may be called by any thread at any time.

udp_listener(address, handler, buffer_size=4096)

Listen for incoming UDP messages

When a message is received, call the handler with the message.

An IUDPListener object is returned.

This method is thread safe. It may be called by any thread at any time.

class zc.ngi.interfaces.IListener

Listener information and close control

This is an implementation interface.

address

The address the listener is listening for connections on.

close(handler=None)

Close the listener and all of its connections

If no handler is passed, the listener and its connections are closed immediately without waiting for any pending input to be handled or for pending output to be sent.

If a handler is passed, the listener will stop accepting new connections and existing connections will be left open. The handler will be called when all of the existing connections have been closed.

connections()

return an iterable of the current connections

class zc.ngi.interfaces.IServerConnection

Server connection

This is an implementation interface.

control

The listener (IListener) that recieved and controls the connection.

class zc.ngi.interfaces.IUDPListener

UDP Listener close control

This is an implementation interface.

close()

Close the listener

NGI Implementations

This section provides additional information about the included NGI implementations. For the most part, any implementation is specified by IImplementation, however, there are a few details of interest for the implementations.

zc.ngi.testing

As its name implies, the testing implementation supports testing application code. It allows testing networking applications without actually creating any sockets and without having to resort to threads or subprocesses.

Like any NGI implementation, the testing implementation is defined by IImplementation. This section expands on the documentation provided by IImplementation.

Note

The testing implementation provides a number of functions and methods not documented here or in the NGI interfaces that were documented in earlier versions of NGI. These should now be viewed as deprecated or internal to the testing implementation.

Addresses are only barely used by the testing implementation. Any hashable object may be used as an address.

class zc.ngi.testing.Connection

The Connection class provides an implementation of IConnection. Connections may be created automatically by the implementation and passed to servers or client connect handlers <zc.ngi.interfaces.IClientConnectHandler, but for testing, you’ll often want to create your own connections so you can pass them to handlers yourself. Connections are created by calling them without arguments:

connection = zc.ngi.testing.Connection()

My default, test connections have handlers that write data to standard output. You can change their handlers using set_handler.

peer

Test connections are used in pairs to simulate both ends of TCP connections. Connections have a peer attribute which represents the other end of a connection. A connection is its peer’s peer. When you pass data to a connection’s write or writelines methods, the data will ultimately be passed to the handle_input method of the connection’s peer.

zc.ngi.async

The async impementation provides a real networking implementation using the asyncore module from the Python standard library. All you really need to know about it is described by the IImplementation interface. This section provides a few additional details of interest.

Addresses are generally 2-tuples having a host address and an integer port. On Unix-like systems, they may also be strings giving names of unix domain sockets.

The listener method also allows None to be passed as an address. If None is passed, a unused port on localhost will be randomly selected. The resulting address can be obtained using the address attribute. This is mainly useful for testing,

The zc.ngi.async modules provides a number of threading modes. See zc.ngi.async implementations and threading.

Table Of Contents

Previous topic

Network Gateway Interface

This Page