The mesh schema is used as an alert and messaging network. Its primary purpose is to ensure message delivery to every participant in the network.

To connect to a mesh network, use the MeshSocket object. This is instantiated as follows:

>>> frompy2pimportmesh>>> sock=mesh.MeshSocket('0.0.0.0',4444)

Using '0.0.0.0' will automatically grab your LAN address. Using an outbound internet connection requires a little more work. First, ensure that you have a port forward set up (NAT busting is not in the scope of this project). Then specify your outward address as follows:

Eventually that will be the default, but while things are being tested it will default to plaintext. If cryptography is not installed, this will generate an ImportError

Specifying a different protocol object will ensure that the node only can connect to people who share its object structure. So if someone has 'mesh2' instead of 'mesh', it will fail to connect. You can see the current default by looking at py2p.mesh.default_protocol.

Unfortunately, this failure is currently silent. Because this is asynchronous in nature, raising an Exception is not possible. Because of this, it’s good to perform the following check after connecting:

To send a message, use the send() method. Each argument supplied will correspond to a packet that the peer receives. In addition, there is a keyed argument you can use. flag will specify how other nodes relay this. These flags are defined in py2p.base.flags. broadcast will indicate that other nodes are supposed to relay it. whisper will indicate that your peers are not supposed to relay it.

>>> sock.send('this is','a test')

Receiving is a bit simpler. When the recv() method is called, it returns a Message object (or None if there are no messages). This has a number of methods outlined which you can find by clicking its name. Most notably, you can get the packets in a message with Message.packets, and reply directly with Message.reply().

In addition to the above, the MeshSocket object has two Events (as supplied by pyee.EventEmitter .

First there’s Event'connect'(). This is called whenever you finalize a connection to your distributed service. It is also called if you reconnect to the service after some failure.

>>> @sock.once('connect')>>> defcall_once(conn):... # conn is a reference to the socket, in case you're in a new scope... # the .once() indicates that this event should only be called once... pass...>>> # sock.once('connect', call_once)>>> # This syntax also works>>>>>> @sock.on('connect')>>> defcall_always(conn):... # conn is still a reference to the socket... # the .on() indicates that this event should be called *every* time... pass...

This class has one other event: Event'message'(). This one is a little bit trickier to use, and it’s recommended that you only have one callback in place at any given time. The event is called any time you receive a message that is not handled by one of the “privileged” callbacks. Such callbacks include the ones for dealing with new peers on the network.

>>> @sock.on('message')>>> defhandle_msg(conn):... # note that you are not passed a reference to the message.... # This means that you must explicitly recv().... msg=conn.recv()... ifmsgisnotNone:... # note the guard clause for if someone else registered a callback... msg.reply('this is an example')...

In addition to this, you can register a custom handler for incoming messages. This is appended to the end of the default handlers. These handlers are then called in a similar way to Javascripts Array.some(). In other words, when a handler returns something true-like, it stops calling handlers.

When writing your handler, keep in mind that you are only passed a Message object and a MeshConnection. Fortunately you can get access to everything you need from these objects.

>>> frompy2pimportmesh,base>>> defregister_1(msg,handler):# Takes in a Message and MeshConnection... packets=msg.packets# This grabs a copy of the packets. Slightly more efficient to store this once.... ifpackets[1]==b'test':# This is the condition we want to act under... msg.reply(b"success")# This is the response we should give... returnTrue# This tells the daemon we took an action, so it should stop calling handlers...>>> defregister_2(msg,handler):# This is a slightly different syntax... packets=msg.packets... ifpackets[1]==b'test':... handler.send(base.flags.whisper,base.flags.whisper,b"success")# One could instead reply to the node who relayed the message... returnTrue...>>> sock=mesh.MeshSocket('0.0.0.0',4444)>>> sock.register_handler(register_1)# The handler is now registered

If this does not take two arguments, register_handler() will raise a ValueError.

This library also supports the EventEmitter API. This enables you to have methods like: