API

There are three main classes in the netdumplings API:

• You subclass DumplingChef to write dumpling chefs.

• You subclass DumplingEater to write dumpling eaters.

• Dumpling instances are passed to the on_dumpling() handler of Python dumpling eaters.

DumplingChef

Note

Implement your own dumpling chefs by subclassing DumplingChef. Your dumpling chef implementations are passed to nd-sniff with the --chef-module flag. See Writing a dumpling chef.

class netdumplings.DumplingChef(kitchen=None)

Base class for all dumpling chefs.

DumplingChef objects are instantiated for you by nd-sniff. You normally won’t need to instantiate DumplingChef objects yourself. Instead you’ll normally subclass DumplingChef in a Python module which you’ll pass to nd-sniff on the commandline.

When instantiated, a DumplingChef registers itself with the given kitchen which will then take care of calling the chef’s packet and interval handlers as appropriate.

This class implements the following methods which will usually be overridden by subclasses:

• packet_handler()

• interval_handler()

Parameters

kitchen (Optional[DumplingKitchen]) – The dumpling kitchen which is providing the network packets used to create the dumplings.

interval_handler(interval=None)

Called automatically at regular intervals by the dumpling kitchen (nd-sniff).

Allows for time-based (rather than purely packet-based) chefs to keep on cheffing even in the absence of fresh packets.

This method is expected to be overridden by child classes. This base implementation does nothing but log a debug entry.

The return value is turned into a dumpling by the kitchen. If None is returned then no dumpling will be created.

Parameters

interval (Optional[int]) – Frequency (in secs) of the time interval pokes.

Return type

Anything which is JSON-serializable.

Returns

Dumpling payload.

packet_handler(packet)

Called automatically by the dumpling kitchen (nd-sniff) whenever a new packet has been sniffed.

This method is expected to be overridden by child classes. This base implementation returns a payload which is the string representation of the packet.

The return value is turned into a dumpling by the kitchen. If None is returned then no dumpling will be created.

Parameters

packet (Raw) – Network packet (from scapy).

Return type

Anything which is JSON-serializable.

Returns

Dumpling payload.

DumplingEater

Note

Implement your own dumpling eaters by subclassing DumplingEater. See Writing a dumpling eater.

class netdumplings.DumplingEater(name='nameless_eater', hub='localhost:11348', *, chef_filter=None, on_connect=None, on_dumpling=None, on_connection_lost=None)

Base helper class for Python-based dumpling eaters.

Connects to nd-hub and listens for any dumplings made by the provided chef_filter (or all chefs if chef_filter is None). Can be given async callables for any of the following events:

on_connect(websocket_uri, websocket_obj)

invoked when the connection to nd-hub is made

on_dumpling(dumpling)

invoked whenever a dumpling is emitted from nd-hub

on_connection_lost(e)

invoked when the connection to nd-hub is closed

The above callables must be async def methods.

Parameters

• name (str) – Name of the dumpling eater. Is ideally unique per eater.

• hub (str) – Address where nd-hub is sending dumplings from.

• chef_filter (Optional[List[str]]) – List of chef names whose dumplings this eater wants to receive. None means get all chefs’ dumplings.

• on_connect (Optional[Callable]) – Called when connection to nd-hub is made. Is passed two parameters: the nd-hub websocket URI (string) and websocket object (websockets.client.WebSocketClientProtocol).

• on_dumpling (Optional[Callable]) – Called whenever a dumpling is received. Is passed the dumpling as a Python dict.

• on_connection_lost (Optional[Callable]) – Called when connection to nd-hub is lost. Is passed the associated exception object.

async on_connect(websocket_uri, websocket_obj)

Default on_connect handler.

This will be used if an on_connect handler is not provided during instantiation, and if a handler is not provided by a DumplingEater subclass.

Only logs an warning-level log entry.

async on_connection_lost(e)

Default on_connection_lost handler.

This will be used if an on_connection_lost handler is not provided during instantiation, and if a handler is not provided by a DumplingEater subclass.

Only logs an warning-level log entry.

async on_dumpling(dumpling)

Default on_dumpling handler.

This will be used if an on_dumpling handler is not provided during instantiation, and if a handler is not provided by a DumplingEater subclass.

Only logs an warning-level log entry.

run(dumpling_count=None)

Run the dumpling eater.

This will block until the desired dumpling_count is met.

Parameters

dumpling_count – Number of dumplings to eat. None means eat forever.

Dumpling

Note

Dumpling instances are created automatically by dumpling kitchens, from the payload returned by a DumplingChef.

Dumpling instances are passed to the on_dumpling() handler of your dumpling eaters.

class netdumplings.Dumpling(*, chef, driver=<DumplingDriver.packet: 1>, creation_time=None, payload)

Represents a single Dumpling.

Dumplings are usually created automatically by a dumpling kitchen from the payload returned by a DumplingChef.

A Dumpling exposes the following attributes:

• chef - the DumplingChef which is responsible for the dumpling payload

• chef_name - the name of the DumplingChef

• kitchen - the name of the kitchen which created the Dumpling

• driver - the DumplingDriver for the dumpling

• creation_time - when the dumpling was created (epoch milliseconds)

• payload - the dumpling payload

Parameters

• chef (Union[DumplingChef, str]) – The chef which created the dumpling payload (usually a DumplingChef instance, but can be a string).

• driver (DumplingDriver) – The event type that drove the dumpling to be created.

• creation_time (Optional[float]) – Dumpling creation time (epoch milliseconds). Defaults to current time.

• payload (Any) – The dumpling payload information. Can be anything (usually a dict) which is JSON-serializable.

classmethod from_json(json_dumpling)

A Dumpling factory which creates a Dumpling from a given json_dumpling string. The given json_dumpling is expected to be a dumpling which has already been JSON-serialized (presumably by a dumpling kitchen).

Parameters

json_dumpling (str) – JSON string to create the Dumpling from.

Returns

A Dumpling instance.

Raise

InvalidDumpling if json_dumpling could not be successfully converted into a Dumpling.

to_json()

Creates a JSON-serialized dumpling string from the Dumpling.

Return type

str

Returns

A JSON string representation of the Dumpling.

Raise

InvalidDumplingPayload if the Dumpling payload cannot be JSON-serialized.

DumplingDriver

class netdumplings.DumplingDriver(value)

The event driving the creation of a Dumpling.

DumplingDriver.packet

a network packet being received by a DumplingChef.

DumplingDriver.interval

a regular time interval poke being received by a DumplingChef.

Exception classes

exception netdumplings.NetDumplingsError

Base exception for all netdumplings errors.

exception netdumplings.InvalidDumpling

A JSON-serialized dumpling does not appear to be valid.

exception netdumplings.InvalidDumplingPayload

A dumpling payload is invalid (probably because it is not JSON-serializable).