Sync Module¶

class py2p.sync.sync_socket(addr, port, prot=<protocol object>, out_addr=None, debug_level=0, leasing=True)[source]¶

This class is used to sync dictionaries between programs. It extends py2p.mesh.mesh_socket

Because of this inheritance, this can also be used as an alert network

This also implements and optional leasing system by default. This leasing system means that if node A sets a key, node B cannot overwrite the value at that key for an hour.

This may be turned off by adding leasing=False to the constructor.

__init__(addr, port, prot=<protocol object>, out_addr=None, debug_level=0, leasing=True)[source]¶

_send_handshake_response(handler)[source]¶: Shortcut method to send a handshake response. This method is extracted from __handle_handshake() in order to allow cleaner inheritence from py2p.sync.sync_socket

set(key, data)[source]¶

Updates the value at a given key.

Parameters:	key – The key that you wish to update. Must be a `str` or `bytes`-like object value – The value you wish to put at this key. Must be a `str` or `bytes`-like object
Raises:	`KeyError` – If you do not have the lease for this slot. Lease is given automatically for one hour if the slot is open.

update(update_dict)[source]¶

Equivalent to dict.update()

This calls sync_socket.__setitem__() for each key/value pair in the given dictionary.

Parameters:	update_dict – A `dict`-like object to extract key/value pairs from. Key and value be a `str` or `bytes`-like object
Raises:	`KeyError` – If you do not have the lease for this slot. Lease is given automatically for one hour if the slot is open.

get(key, ifError=None)[source]¶

Retrieves the value at a given key.

Parameters:	key – The key that you wish to check. Must be a `str` or `bytes`-like object ifError – The value you wish to return on exception (default: `None`)
Returns:	The value at said key, or the value at ifError if there’s an Exception

keys()[source]¶: Returns an iterator of the underlying :py:class:`dict`s keys

__iter__()[source]¶: Returns an iterator of the underlying :py:class:`dict`s keys

values()[source]¶: Returns an iterator of the underlying :py:class:`dict`s values

items()[source]¶: Returns an iterator of the underlying :py:class:`dict`s items

pop(key, *args)[source]¶

Returns a value, with the side effect of deleting that association

Parameters:	Key – The key you wish to look up. Must be a `str` or `bytes`-like object ifError – The value you wish to return on Exception (default: raise an Exception)
Returns:	The value of the supplied key, or `ifError`
Raises:	`KeyError` – If the key does not have an associated value

popitem()[source]¶

Returns an association, with the side effect of deleting that association

Returns:	An arbitrary association

copy()[source]¶: Returns a dict copy of this synchronized hash table

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

_handle_peers(msg, handler)¶

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

Parameters:	msg – A `message` handler – A `mesh_connection`
Returns:	Either `True` or `None`

_mesh_socket__clean_waterfalls()¶

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

Delete all duplicates
Delete all older than 60 seconds

_mesh_socket__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

Parameters:	msg – A `message` handler – A `mesh_connection`
Returns:	Either `True` or `None`

_mesh_socket__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

Parameters:	msg – A `message` handler – A `mesh_connection`
Returns:	Either `True` or `None`

_mesh_socket__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

Parameters:	msg – A `message` handler – A `mesh_connection`
Returns:	Either `True` or `None`

_mesh_socket__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.

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

_send_handshake(handler)¶

Shortcut method for sending a handshake to a given handler

Parameters:	handler – A `mesh_connection`

_sync_socket__handle_store(msg, handler)¶

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

store data in a given key

delete data in a given key

Args:

msg: A message handler: A mesh_connection

Returns:

Either True or None

_sync_socket__store(key, new_data, new_meta, error=True)¶

Private API method for storing data. You have permission to store something if:

The network is not enforcing leases, or
There is no value at that key, or
The lease on that key has lapsed (not been set in the last hour), or
You are the owner of that key

Parameters:	key – The key you wish to store data at new_data – The data you wish to store in said key new_meta – The metadata associated with this storage error – A boolean which says whether to raise a `KeyError` if you can’t store there
Raises:	`KeyError` – If someone else has a lease at this value, and `error` is `True`

close()¶

If the socket is not closed, close the socket

Raises:	`RuntimeError` – The socket was already closed

connect(addr, port, id=None, conn_type=<class 'py2p.mesh.mesh_connection'>)¶

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.mesh_socket('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

Parameters:	addr – A string address port – A positive, integral port id – A string-like object which represents the expected ID of this node

disconnect(handler)¶

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

Parameters:	handler – the connection you would like to close

handle_msg(msg, conn)¶

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

Parameters:	msg – A `py2p.base.message` object conn – A `py2p.base.base_connection` object
Returns:	True if an action was taken, None if not.

incoming¶: IDs of incoming connections

outgoing¶: IDs of outgoing connections

recv(quantity=1)¶

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 :py:class:`~py2p.base.message`s you would like to pull (default: 1)
Returns:	A list of `message` s, an empty list, a single `message` , or `None`

register_handler(method)¶

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.base_connection` 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

request_peers()¶: Requests your peers’ routing tables

send(*args, **kargs)¶

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

Parameters:	args – A list of strings or bytes-like 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.

Warning

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.

status¶

The status of the socket.

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

waterfall(msg)¶

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.

class py2p.sync.metatuple[source]¶: This class is used to store metadata for a particular key