Base Module¶

A library to store common functions and protocol definitions

class py2p.base.flags[source]¶

A namespace to hold protocol-defined flags

reserved = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47)¶

Main flags:

broadcast¶
whisper¶
renegotiate¶
ping¶
pong¶

Sub-flags:

broadcast
compression¶
whisper
handshake¶
ping
pong
notify¶
peers¶
request¶
resend¶
response¶
store¶
retrieve¶

Python-implemented compression methods:

bz2¶
gzip¶
lzma¶
snappy¶
zlib¶

Other implementations’ and/or planned compression methods:

bwtc¶
context1¶
defsum¶
dmc¶
fenwick¶
huffman¶
lzjb¶
lzjbr¶
lzp3¶
mtf¶
ppmd¶
simple¶

class py2p.base.Protocol[source]¶

Defines service variables so that you can reject connections looking for a different service

subnet¶: The subnet flag this Protocol uses

encryption¶: The encryption method this Protocol uses

id¶: The SHA-256 based ID of this Protocol

class py2p.base.BaseConnection(*args, **kwargs)[source]¶

The base class for a connection

__init__(*args, **kwargs)¶

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

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

active¶

addr¶

buffer¶

collect_incoming_data(data)[source]¶

Collects incoming data

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

compression¶

expected¶

fileno()[source]¶: Mirror for the fileno() method of the connection’s underlying socket

find_terminator()[source]¶: Returns whether the defined return sequences is found

found_terminator()[source]¶: Processes received messages

handle_renegotiate(packets)[source]¶

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

id¶

last_sent¶

outgoing¶

protocol¶: Returns server.protocol

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

Sends a message through its connection.

Parameters:	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)
Returns:	the `IntenalMessage` object you just sent, or `None` if the sending was unsuccessful

send_InternalMessage(msg)[source]¶

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

server¶

sock¶

time¶

class py2p.base.BaseDaemon(*args, **kwargs)[source]¶

The base class for a daemon

__init__(*args, **kwargs)¶

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

Parameters:	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
Raises:	`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

_logger¶

alive¶

conn_type¶

daemon¶

exceptions¶

kill_old_nodes(handler)[source]¶: Cleans out connections which never finish a message

main_thread¶

process_data(handler)[source]¶: Collects incoming data from nodes

protocol¶: Returns server.protocol

server¶

sock¶

class py2p.base.BaseSocket(*args, **kwargs)[source]¶

The base class for a peer-to-peer socket abstractor

digraph inheritanced29a878b3a { rankdir=LR; size="8.0, 12.0"; "py2p.base.BaseSocket" [URL="#py2p.base.BaseSocket",fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",target="_top",tooltip="The base class for a peer-to-peer socket abstractor"]; "pyee.EventEmitter" -> "py2p.base.BaseSocket" [arrowsize=0.5,style="setlinewidth(0.5)"]; "pyee.EventEmitter" [fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5)",tooltip="The EventEmitter class."]; }

_BaseSocket__closed¶

_BaseSocket__handlers¶

__init__(*args, **kwargs)¶

Initializes a peer to peer socket

Parameters:

addr – The address you wish to bind to (ie: “192.168.1.1”)
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 ‘0.0.0.0’ 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

Raises:

socket.error – The address you wanted could not be bound, or is
otherwise used

_logger¶

awaiting_ids¶

close()[source]¶

If the socket is not closed, close the socket

Raises:	`RuntimeError` – The socket was already closed

debug_level¶

handle_msg(msg, conn)[source]¶

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

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

id¶

incoming¶: IDs of incoming connections

out_addr¶

outgoing¶: IDs of outgoing connections

protocol¶

register_handler(method)[source]¶

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

routing_table¶

status¶

The status of the socket.

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

class py2p.base.InternalMessage(msg_type, sender, payload, compression=None, timestamp=None)[source]¶

An object used to build and parse protocol-defined message structures

_InternalMessage__clear_cache()¶

_InternalMessage__compression¶

classmethod _InternalMessage__decompress_string(string, compressions=None)¶

Returns a tuple containing the decompressed bytes and a boolean as to whether decompression failed or not

Parameters:	string – The possibly-compressed message you wish to parse compressions – A list of the standard compression methods this message may be under (default: [])
Returns:	A decompressed version of the message
Raises:	`ValueError` – Unrecognized compression method fed in compressions

Warning

Do not feed it with the size header, it will throw errors

_InternalMessage__full_string¶

_InternalMessage__id¶

_InternalMessage__msg_type¶

_InternalMessage__non_len_string¶

Returns a bytes object containing the entire message, excepting the total length header

Raises:

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

bool
float
int (if 2**64 > x > -2**63)
str
bytes
unicode
tuple
list
dict (if all keys are unicode)

_InternalMessage__payload¶

classmethod _InternalMessage__sanitize_string(string, sizeless=False)¶

Removes the size header for further processing. Also checks if the header is valid.

Parameters:	string – The string you wish to sanitize sizeless – Whether this string is missing a size header (default: `False`)
Returns:	The fed string without the size header
Raises:	`AttributeError` – Fed a non-string, non-bytes argument `AssertionError` – Initial size header is incorrect

_InternalMessage__sender¶

_InternalMessage__string¶

_InternalMessage__time¶

__init__(msg_type, sender, payload, compression=None, timestamp=None)[source]¶

Initializes a InternalMessage instance

Parameters:

msg_type – A bytes-like header for the message you wish to send
sender – A bytes-like sender ID the message is using
payload – A iterable of bytes-like objects containing the payload of the message
compression – A list of the compression methods this message may use (default: [])
timestamp – The current UTC timestamp (as an integer) (default: result of utils.getUTC())

Raises:

TypeError – If you feed an object which cannot convert to bytes

Warning

If you feed a unicode object, it will be decoded using utf-8. All other objects are treated as raw bytes. If you desire a particular codec, encode it yourself before feeding it in.

compression¶

compression_fail¶

compression_used¶: Returns the compression method this message is using

classmethod feed_string(string, sizeless=False, compressions=None)[source]¶

Constructs a InternalMessage from a string or bytes object.

Parameters:	string – The string you wish to parse sizeless – A boolean which describes whether this string has its size header (default: it does) compressions – A list containing the standardized compression methods this message might be under (default: [])
Returns:	A base.InternalMessage from the given string
Raises:	`AttributeError` – Fed a non-string, non-bytes argument `AssertionError` – Initial size header is incorrect `ValueError` – Unrecognized compression method fed in compressions `IndexError` – Packet headers are incorrect OR unrecognized compression

id¶: Returns the message id

msg_type¶

packets¶: Returns the full tuple of packets in this message encoded as bytes, excluding the header

payload¶: Returns a tuple containing the message payload encoded as bytes

sender¶

string¶

Returns a bytes representation of the message

Raises:	`TypeError` – See `_InternalMessage__non_len_string()`

time¶

time_58¶: Returns this message’s timestamp in base_58

class py2p.base.Message(msg, server)[source]¶

An object which gets returned to a user, containing all necessary information to parse and reply to a message

__init__(msg, server)[source]¶

Initializes a Message object

Parameters:	msg – A `py2p.base.InternalMessage` object server – A `py2p.base.BaseSocket` object

id¶: Returns the message id

msg¶

packets¶: Returns a tuple containing the message payload encoded as bytes

reply(*args)[source]¶

Replies to the sender if you’re directly connected. Tries to make a connection otherwise

Parameters:	args – Each argument given is a packet you wish to send. This is prefixed with base.flags.whisper, so the other end will receive `[base.flags.whisper, args]`

sender¶: The ID of this Message’s sender

server¶

time¶: The time this Message was sent at

time_58¶: Returns this message’s timestamp in base_58

py2p.base.compress(msg, method)[source]¶

Shortcut method for compression

Parameters:	msg – The message you wish to compress, the type required is defined by the requested method method – The compression method you wish to use. Supported (assuming installed): `gzip` `zlib` `bz2` `lzma`
Returns:	Defined by the compression method, but typically the bytes of the compressed message

Warning

The types fed are dependent on which compression method you use. Best to assume most values are bytes or bytearray

Raises:	A :py:class:`ValueError` if there is an unknown compression method, – or a method-specific error

py2p.base.decompress(msg, method)[source]¶

Shortcut method for decompression

Parameters:	msg – The message you wish to decompress, the type required is defined by the requested method method – The decompression method you wish to use. Supported (assuming installed): `gzip` `zlib` `bz2` `lzma`
Returns:	Defined by the decompression method, but typically the bytes of the compressed message

Warning

The types fed are dependent on which decompression method you use. Best to assume most values are bytes or bytearray

Raises:	A :py:class:`ValueError` if there is an unknown compression method, – or a method-specific error

py2p.base.from_base_58(string)[source]¶

Takes a base_58 string and returns its corresponding integer

Parameters:	string – The base_58 value you wish to decode (string, bytes, or bytearray)
Returns:	Returns integral value which corresponds to the fed string

py2p.base.pack_value(l, i)[source]¶

For value i, pack it into bytes of size length

Parameters:	length – A positive, integral value describing how long to make the packed array i – A positive, integral value to pack into said array
Returns:	A bytes object containing the given value
Raises:	`ValueError` – If length is not large enough to contain the value provided

py2p.base.to_base_58(i)[source]¶

Takes an integer and returns its corresponding base_58 string

Parameters:	i – The integral value you wish to encode
Returns:	A `bytes` object which contains the base_58 string
Raises:	`TypeError` – If you feed a non-integral value

py2p.base.unpack_value(string)[source]¶

For a string, return the packed value inside of it

Parameters:	string – A string or bytes-like object
Returns:	An integral value interpreted from this, as if it were a big-endian, unsigned integral