Mesh Module

class py2p.mesh.MeshConnection(*args, **kwargs)[source]

The class for mesh connection abstraction. This inherits from py2p.base.BaseConnection

Inheritance diagram of py2p.mesh.MeshConnection
send(msg_type, *args, **kargs)[source]

Sends a message through its connection.

  • msg_type – Message type, corresponds to the header in a InternalMessage object
  • *args – A list of bytes-like objects, which correspond to the packets to send to you
  • **kargs – There are two available keywords:
  • id – The ID this message should appear to be sent from (default: your ID)
  • time – The time this message should appear to be sent from (default: now in UTC)

the IntenalMessage object you just sent, or None if the sending was unsuccessful


Processes received messages

handle_waterfall(msg, packets)[source]

This method determines whether this message has been previously received or not.

If it has been previously received, this method returns True.

If it is older than a preset limit, this method returns True.

Otherwise this method returns False, and forwards the message appropriately.

  • msg – The message in question
  • packets – The message’s packets

Either True or False

__init__(*args, **kwargs)

Sets up a connection to another peer-to-peer socket

  • sock – The connected socket object
  • server – A reference to your peer-to-peer socket
  • outgoing – Whether this connection is outgoing (default: False)

Collects incoming data

Parameters:data – The most recently received bytes
Returns:True if the data collection was successful, False if the connection was closed

Mirror for the fileno() method of the connection’s underlying socket


Returns whether the defined return sequences is found


The handler for connection renegotiations

This is to deal with connection maintenance. For instance, it could be that a compression method fails to decode on the other end, and a node will need to renegotiate which methods it is using. Hence the name of the flag associated with it, “renegotiate”.

Parameters:packets – A tuple containing the packets received in this message
Returns:True if an action was taken, False if not

Returns server.protocol


Sends a preconstructed message

Parameters:msg – The IntenalMessage you wish to send
Returns:the IntenalMessage object you just sent, or None if the sending was unsuccessful
class py2p.mesh.MeshDaemon(*args, **kwargs)[source]

The class for mesh daemon. This inherits from py2p.base.BaseDaemon

Inheritance diagram of py2p.mesh.MeshDaemon
__init__(*args, **kwargs)

Sets up a daemon process for your peer-to-peer socket

  • addr – The address you wish to bind to
  • port – The port you wish to bind to
  • server – A reference to the peer-to-peer socket
  • socket.error – The address you wanted is already in use
  • ValueError – If your peer-to-peer socket is set up with an unknown encryption method

Daemon thread which handles all incoming data and connections


Handle an incoming connection


Cleans out connections which never finish a message


Collects incoming data from nodes


Returns server.protocol

class py2p.mesh.MeshSocket(*args, **kwargs)[source]

The class for mesh socket abstraction. This inherits from py2p.base.BaseSocket

Inheritance diagram of py2p.mesh.MeshSocket

Added Events:

Event 'connect'(conn)

This event is called whenever you have a new connection to the service network. In other words, whenever the length of your routing table is increased from zero to one.

If you call on('connect'), that will be executed on every connection to the network. So if you are suddenly disconnected, and manage to recover, that function will execute again.

To avoid this, call once('connect'). That will usually be more correct.

Parameters:conn (py2p.mesh.MeshSocket) – A reference to this abstract socket
Event 'message'(conn)

This event is called whenever you receive a new message. A reference to the message is not passed to you. This is to prevent potential memory leaks.

If you want to register a “privileged” handler which does get a reference to the message, see register_handler()

Parameters:conn (py2p.mesh.MeshSocket) – A reference to this abstract socket
__init__(*args, **kwargs)

Initializes a mesh socket

  • addr – The address you wish to bind to (ie: “”)
  • port – The port you wish to bind to (ie: 44565)
  • prot – The Protocol you wish to operate over, defined by a py2p.base.Protocol object
  • out_addr – Your outward facing address. Only needed if you’re connecting over the internet. If you use ‘’ for the addr argument, this will automatically be set to your LAN address.
  • debug_level – The verbosity you want this socket to use when printing event data

SocketException – The address you wanted could not be bound, or is otherwise used

handle_msg(msg, conn)[source]

Decides how to handle various message types, allowing some to be handled automatically


True if an action was taken, None if not.


This function is used to generate a list-formatted group of your peers. It goes in format [ ((addr, port), ID), ...]


Shortcut method for sending a handshake to a given handler

Parameters:handler – A MeshConnection

Shortcut method to send a handshake response. This method is extracted from __handle_handshake() in order to allow cleaner inheritence from py2p.sync.SyncSocket

_handle_peers(msg, handler)[source]

This callback is used to deal with peer signals. Its primary jobs is to connect to the given peers, if this does not exceed py2p.mesh.max_outgoing


Either True or None

send(*args, **kargs)[source]

This sends a message to all of your peers. If you use default values it will send it to everyone on the network

  • *args – A list of objects you want your peers to receive
  • **kargs – There are two keywords available:
  • flag – A string or bytes-like object which defines your flag. In other words, this defines packet 0.
  • type – A string or bytes-like object which defines your message type. Changing this from default can have adverse effects.

TypeError – If any of the arguments are not serializable. This means your objects must be one of the following:


If you change the type attribute from default values, bad things could happen. It MUST be a value from py2p.base.flags, and more specifically, it MUST be either broadcast or whisper. The only other valid flags are waterfall and renegotiate, but these are RESERVED and must NOT be used.


This function handles message relays. Its return value is based on whether it took an action or not.

Parameters:msg – The Message in question
Returns:True if the message was then forwarded. False if not.
connect(addr, port, id=None, conn_type=<class 'py2p.mesh.MeshConnection'>)[source]

This function connects you to a specific node in the overall network. Connecting to one node should connect you to the rest of the network, however if you connect to the wrong subnet, the handshake failure involved is silent. You can check this by looking at the truthiness of this objects routing table. Example:

>>> conn = mesh.MeshSocket('localhost', 4444)
>>> conn.connect('localhost', 5555)
>>> # do some other setup for your program
>>> if not conn.routing_table:
...     conn.connect('localhost', 6666)  # any fallback address
  • addr – A string address
  • port – A positive, integral port
  • id – A string-like object which represents the expected ID of this node

Closes a given connection, and removes it from your routing tables

Parameters:handler – the connection you would like to close

Requests your peers’ routing tables


This function cleans the set of recently relayed messages based on the following heuristics:

  • Delete all older than 60 seconds
_MeshSocket__handle_handshake(msg, handler)

This callback is used to deal with handshake signals. Its three primary jobs are:

  • reject connections seeking a different network
  • set connection state
  • deal with connection conflicts

Either True or None

_MeshSocket__handle_request(msg, handler)

This callback is used to deal with request signals. Its three primary jobs are:

  • respond with a peers signal if packets[1] is '*'
  • if you know the ID requested, respond to it
  • if you don’t, make a request with your peers

Either True or None

_MeshSocket__handle_response(msg, handler)

This callback is used to deal with response signals. Its two primary jobs are:

  • if it was your request, send the deferred message
  • if it was someone else’s request, relay the information

Either True or None

_MeshSocket__resolve_connection_conflict(handler, h_id)

Sometimes in trying to recover a network a race condition is created. This function applies a heuristic to try and organize the fallout from that race condition. While it isn’t perfect, it seems to have increased connection recovery rate from ~20% to ~75%. This statistic is from memory on past tests. Much improvement can be made here, but this statistic can likely never be brought to 100%.

In the failure condition, the overall network is unaffected for large networks. In small networks this failure condition causes a fork, usually where an individual node is kicked out.

  • handler – The handler with whom you have a connection conflict
  • h_id – The id of this handler

If the socket is not closed, close the socket

Raises:RuntimeError – The socket was already closed
emit(event, *args, **kwargs)

Emit event, passing *args and **kwargs to each attached function. Returns True if any functions are attached to event; otherwise returns False.


ee.emit('data', '00101001')

Assuming data is an attached function, this will call data('00101001')'.

For coroutine event handlers, calling emit is non-blocking. In other words, you do not have to await any results from emit, and the coroutine is scheduled in a fire-and-forget fashion.


IDs of incoming connections


Returns the list of all listeners registered to the event.

on(event, f=None)

Registers the function (or optionally an asyncio coroutine function) f to the event name event.

If f isn’t provided, this method returns a function that takes f as a callback; in other words, you can use this method as a decorator, like so:

def data_handler(data):

As mentioned, this method can also take an asyncio coroutine function:

async def data_handler(data)
    await do_async_thing(data)

This will automatically schedule the coroutine using the configured scheduling function (defaults to asyncio.ensure_future) and the configured event loop (defaults to asyncio.get_event_loop()).

once(event, f=None)

The same as ee.on, except that the listener is automatically removed after being called.


IDs of outgoing connections


This function has two behaviors depending on whether quantity is left as default.

If quantity is given, it will return a list of Message objects up to length quantity.

If quantity is left alone, it will return either a single Message object, or None

Parameters:quantity – The maximum number of Message s you would like to pull (default: 1)
Returns:A list of Message s, an empty list, a single Message , or None

Register a handler for incoming method.

Parameters:method – A function with two given arguments. Its signature should be of the form handler(msg, handler), where msg is a py2p.base.Message object, and handler is a py2p.base.BaseConnection object. It should return True if it performed an action, to reduce the number of handlers checked.
Raises:ValueError – If the method signature doesn’t parse correctly

Remove all listeners attached to event. If event is None, remove all listeners on all events.

remove_listener(event, f)

Removes the function f from event.


The status of the socket.

Returns:"Nominal" if all is going well, or a list of unexpected (Exception, traceback) tuples if not