# circuits.net.events module

Networking Events

This module implements commonly used Networking events used by socket components.

class circuits.net.events.connect(*args, **kwargs)

  Bases: `Event`

  connect Event

  This Event is sent when a new client connection has arrived on a server. This event is also used for client’s to initiate a new connection to a remote host.

  Note

  This event is used for both Client and Server Components.

  Parameters:

    - args (tuple) – Client: (host, port) Server: (sock, host, port)

    - kwargs (dict) – Client: (ssl)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.disconnect(*args, **kwargs)

  Bases: `Event`

  disconnect Event

  This Event is sent when a client connection has closed on a server. This event is also used for client’s to disconnect from a remote host.

  Note

  This event is used for both Client and Server Components.

  Parameters:

    args – Client: () Server: (sock)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.connected(host, port)

  Bases: `Event`

  connected Event

  This Event is sent when a client has successfully connected.

  Note

  This event is for Client Components.

  Parameters:

    - host – The hostname connected to.

    - port – The port connected to

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.disconnected

  Bases: `Event`

  disconnected Event

  This Event is sent when a client has disconnected

  Note

  This event is for Client Components.

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.read(*args)

  Bases: `Event`

  read Event

  This Event is sent when a client or server connection has read any data.

  Note

  This event is used for both Client and Server Components.

  Parameters:

    args – Client: (data) Server: (sock, data)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.error(*args)

  Bases: `Event`

  error Event

  This Event is sent when a client or server connection has an error.

  Note

  This event is used for both Client and Server Components.

  Parameters:

    args – Client: (error) Server: (sock, error)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.unreachable(host, port, reason=None)

  Bases: `Event`

  unreachable Event

  This Event is sent when a server is unreachable for a client

  Parameters:

    - host – Server hostname or IP

    - port – Server port

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.broadcast(*args)

  Bases: `Event`

  broadcast Event

  This Event is used by the UDPServer/UDPClient sockets to send a message on the `<broadcast>` network.

  Note

  - This event is never sent, it is used to send data.

  - This event is used for both Client and Server UDP Components.

  Parameters:

    args – (data, port)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.write(*args)

  Bases: `Event`

  write Event

  This Event is used to notify a client, client connection or server that we have data to be written.

  Note

  - This event is never sent, it is used to send data.

  - This event is used for both Client and Server Components.

  Parameters:

    args – Client: (data) Server: (sock, data)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.close(*args)

  Bases: `Event`

  close Event

  This Event is used to notify a client, client connection or server that we want to close.

  Note

  - This event is never sent, it is used to close.

  - This event is used for both Client and Server Components.

  Parameters:

    args – Client: () Server: (sock)

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.ready(component, bind=None)

  Bases: `Event`

  ready Event

  This Event is used to notify the rest of the system that the underlying Client or Server Component is ready to begin processing connections or incoming/outgoing data. (This is triggered as a direct result of having the capability to support multiple client/server components with a single poller component instance in a system).

  Note

  This event is used for both Client and Server Components.

  Parameters:

    - component – The Client/Server Component that is ready.

    - bind – The (host, port) the server has bound to.

  x.__init__(…) initializes x; see x.__class__.__doc__ for signature

class circuits.net.events.closed(*args, **kwargs)

  Bases: `Event`

  closed Event

  This Event is sent when a server has closed its listening socket.

  Note

  This event is for Server components.

  An event is a message send to one or more channels. It is eventually dispatched to all components that have handlers for one of the channels and the event type.

  All normal arguments and keyword arguments passed to the constructor of an event are passed on to the handler. When declaring a handler, its argument list must therefore match the arguments used for creating the event.

  Every event has a `name` attribute that is used for matching the event with the handlers.

  Variables:

    - channels –

      an optional attribute that may be set before firing the event. If defined (usually as a class variable), the attribute specifies the channels that the event should be delivered to as a tuple. This overrides the default behavior of sending the event to the firing component’s channel.

      When an event is fired, the value in this attribute is replaced for the instance with the channels that the event is actually sent to. This information may be used e.g. when the event is passed as a parameter to a handler.

    - value – this is a `circuits.core.values.Value` object that holds the results returned by the handlers invoked for the event.

    - success – if this optional attribute is set to `True`, an associated event `success` (original name with “_success” appended) will automatically be fired when all handlers for the event have been invoked successfully.

    - success_channels – the success event is, by default, delivered to same channels as the successfully dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

    - complete – if this optional attribute is set to `True`, an associated event `complete` (original name with “_complete” appended) will automatically be fired when all handlers for the event and all events fired by these handlers (recursively) have been invoked successfully.

    - complete_channels – the complete event is, by default, delivered to same channels as the initially dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

class circuits.net.events.starttls(sock)

  Bases: `Event`

  starttls Event

  This event can be fired to upgrade the socket connection to a TLS secured connection.

  Note

  This event is currently only available for Server Components.

  Parameters:

    sock (socket.socket) – The client socket where to start TLS.

  An event is a message send to one or more channels. It is eventually dispatched to all components that have handlers for one of the channels and the event type.

  All normal arguments and keyword arguments passed to the constructor of an event are passed on to the handler. When declaring a handler, its argument list must therefore match the arguments used for creating the event.

  Every event has a `name` attribute that is used for matching the event with the handlers.

  Variables:

    - channels –

      an optional attribute that may be set before firing the event. If defined (usually as a class variable), the attribute specifies the channels that the event should be delivered to as a tuple. This overrides the default behavior of sending the event to the firing component’s channel.

      When an event is fired, the value in this attribute is replaced for the instance with the channels that the event is actually sent to. This information may be used e.g. when the event is passed as a parameter to a handler.

    - value – this is a `circuits.core.values.Value` object that holds the results returned by the handlers invoked for the event.

    - success – if this optional attribute is set to `True`, an associated event `success` (original name with “_success” appended) will automatically be fired when all handlers for the event have been invoked successfully.

    - success_channels – the success event is, by default, delivered to same channels as the successfully dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.

    - complete – if this optional attribute is set to `True`, an associated event `complete` (original name with “_complete” appended) will automatically be fired when all handlers for the event and all events fired by these handlers (recursively) have been invoked successfully.

    - complete_channels – the complete event is, by default, delivered to same channels as the initially dispatched event itself. This may be overridden by specifying an alternative list of destinations using this attribute.