Skip to main content

A python library for peer-to-peer networking

Project description

Skip to file-wise API

Read about the protocol

New in this release:

  • No longer compatible with py2p-0.2.*
  • Add deprecation warning for net.py
  • Add experimental SSL encryption
  • Add connection conflict resolution
  • Add experimental network repair functions (on disconnect, request your peers’ peers)
  • Add protocol rejection test
  • Change behavior of request *
  • Move disconnect method from mesh_daemon to mesh_socket
  • Rewrite protocol documentation
  • Reduce max outgoing connections (8 -> 4)
  • No longer accepts waterfall packets >60s old
  • No longer limit length of waterfall queue

Public API

Constants

  • __version__: A string containing the major, minor, and patch release number.
  • version_info: A tuple version of the above
  • protocol_version: A string containing the major and minor release number. This refers to the underlying protocol
  • node_policy_version: A string containing the build number associated with this version. This refers to the node and its policies.

Classes

File-wise API

base.py

This is used mostly for inheriting common functions with mesh.py and the planned chord.py

Constants

  • version: A string containing the major, minor, and patch release number. This version refers to the underlying protocol.
  • protocol_version: A string containing the major and minor release number. This refers to the underlying protocol
  • node_policy_version: A string containing the build number associated with this version. This refers to the node and its policies.
  • user_salt: A uuid4 which is generated uniquely in each running instance
  • compression: A list of the compression methods your instance supports
  • default_protocol: The default protocol definition. This uses an empty string as the subnet and SSL encryption, as supplied by ssl_wrapper.py (in alpha releases this will use Plaintext)
  • base_58: The characterspace of base_58, ordered from least to greatest value

Methods

  • to_base_58(i): Takes an int (or long) and returns its corresponding base_58 string (type: bytes)
  • from_base_58(string): Takes a base_58 string (or bytes) and returns its corresponding integer (type: int, long)
  • getUTC(): Returns the current unix time in UTC (type: int)
  • compress(msg, method): Shortcut method for compression (type: bytes)
  • decompress(msg, method): Shortcut method for decompression (type: bytes)
  • get_lan_ip(): Returns either your current local IP, or "127.0.0.1"

Classes

flags

This class is used as a namespace to store the various protocol defined flags.

  • broadcast
  • bz2
  • compression
  • gzip
  • handshake
  • lzma
  • peers
  • waterfall
  • resend
  • response
  • renegotiate
  • request
  • whisper

pathfinding_message

This class is used internally to deal with packet parsing from a socket level. If you find yourself calling this as a user, something’s gone wrong.

Constructor

pathfinding_message(protocol, msg_type, sender, payload, compressions=None) pathfinding_message.feed_string(protocol, string, sizeless=False, compressions=None)

  • protocol: The protocol this message uses
  • msg_type: The chief flag this message uses, to broadcast intent
  • sender: The SHA384-based sender ID
  • payload: A list of additional packets to send
  • compressions: A list of possible compression methods used/to use
  • string: The raw message to parse
  • sizeless: An indicator as to whether this message contains the length header
Constants
  • protocol: The protocol this message is sent under
  • msg_type: The main flag of the message (ie: ['broadcast', 'waterfall', 'whisper', 'renegotiate'])
  • sender: The sender id of this message
  • time: An int of the message’s timestamp
  • compression: The list of compression methods this message may be under
  • compression_fail: A debug property which is triggered if you give compression methods, but the message fed from feed_string is actually in plaintext
Properties
  • payload: Returns the message’s payload
  • compression_used: Returns the compression method used
  • time_58: Returns the timestamp in base_58
  • id: Returns the message’s id
  • len: Returns the messages length header
  • packets: Returns a list of the packets in this message, excluding the length header
  • string: Returns a string version of the message, including the length header
  • __non_len_string: Returns the string of this message without the size header
Methods
  • __len__(): Returns the length of this message excluding the length header
Class Methods
  • feed_string(ptorocol, string, sizeless=False, compressions=None): Given a protocol, a string or bytes, process this into a pathfinding_message. If compressions are enabled, you must provide a list of possible methods. If the size header is not included, you must specify this with sizeless=True. Possible errors:
    • AttributeError: Fed a non-string, non-bytes argument
    • AssertionError: Initial size header is incorrect
    • Exception: Unrecognized compression method fed in compressions
    • struct.error: Packet headers are incorrect OR unrecognized compression
    • IndexError: See struct.error
  • sanitize_string(string, sizeless=False): Given an str or bytes, returns a bytes object with no size header. Possible errors:
    • AttributeError: Fed a non-string, non-bytes argument
    • AssertionError: Initial size header is incorrect
  • decompress_string(string, compressions=None): Given a bytes object and list of possible compression methods, returns a decompressed version and a bool indicating if decompression failed. If decompression occurs, this will always return bytes. If not, it will return whatever you pass in. Decompression failure is defined as it being unable to decompress despite a list of possible methods being provided. Possible errors:
    • Exception: Unrecognized compression method fed in compressions
  • process_string(string): Given a bytes, return a list of its contained packets. Possible errors:
    • IndexError: Packet headers are incorrect OR not fed plaintext
    • struct.error: See IndexError OR fed non-bytes object

message

This class is returned to the user when a non-automated message is received. It contains sufficient information to parse a message or reply to it.

Constructor

message(msg, server)

Constants
Properties
  • time: The UTC Unix time at which the message was sent
  • sender: The original sender’s ID
  • protocol: The protocol you received this under
  • packets: Returns a list of the packets received, with the first item being the subflag
  • id: Returns the SHA384-based message id
Methods
  • reply(*args): Sends a whisper to the original sender with the arguments being each packet after that. If you are not connected, it uses the request/response mechanism to try making a connection

protocol

This class inherits most of its methods from a namedtuple. This means that each of the properties in the constructor can be accessed by name or index. Mostly you’ll be doing this by name.

Constructor

protocol(subnet, encryption)

Constants
  • subnet: A flag to allow people with the same package version to operate different networks
  • encryption: Defines the encryption standard used on the socket
Properties
  • id: Returns the SHA256-based protocol id

base_socket

Variables
  • debug_level: The verbosity of the socket with debug prints
  • routing_table: The current dict of peers in format {id: connection}
  • awaiting_ids: A list of connections awaiting a handshake
  • queue: A deque of recently received messages
  • daemon: This node’s base_daemon object
Properties
  • outgoing: A list of ids for outgoing connections
  • incoming: A list of ids for incoming connections
  • status: Returns "Nominal" or base_socket.daemon.exceptions if there are Exceptions collected
Methods
  • recv(quantity=1): Receive messages; If quantity != 1, returns a list of messages, otherwise returns one
  • __print__(*args, level=None): Prints debug information if level >= debug_level

base_daemon

Constructor

base_daemon(addr, port, server, prot=default_protocol)

  • addr: The address it should bind its incoming connection to
  • port: The port it should bind its incoming connection to
  • server: This daemon’s base_socket
  • prot: This daemon’s protocol
Variables
  • protocol: This daemon’s protocol object
  • server: A pointer to this daemon’s base_socket
  • sock: This daemon’s socket object
  • alive: A checker to shutdown the daemon. If False, its thread will stop running eventually.
  • exceptions: A list of unhandled Exceptions raised in mainloop
  • daemon: A Thread which runs through mainloop
Methods
  • __print__(*args, level=None): Prints debug information if level >= server.debug_level

base_connection

Constructor

base_connection(sock, server, prot=default_protocol, outgoing=False)

  • sock: A socket.socket
  • server: This node’s base_socket
  • prot: This node’s protocol
  • outgoing: Whether or not this node is an outgoing connection
Variables
  • sock: This connection’s socket object
  • server: A pointer to this connection’s base_socket object
  • protocol: This connection’s protocol object
  • outgoing: A bool that states whether this connection is outgoing
  • buffer: A list of recently received characters
  • id: This node’s SHA384-based id
  • time: The time at which this node last received data
  • addr: This node’s outward-facing address
  • compression: A list of this node’s supported compression methods
  • last_sent: A copy of the most recently sent whisper or broadcast
  • expected: The number of bytes expected in the next message
  • active: A bool which says whether the next message is a size header, or a message (True if message)
Methods
  • fileno(): Returns sock’s file number
  • collect_incoming_data(data): Adds new data to the buffer
  • find_terminator(): Determines if a message has been fully received (name is a relic of when this had an end_of_tx flag)
  • __print__(*args, level=None): Prints debug information if level >= server.debug_level

mesh.py

Note: This inherits a lot from base.py, and imported values will not be listed here, for brevity’s sake.

Constants

  • compression: A list of the compression methods your instance supports
  • max_outgoing: The (rough) maximum number of outgoing connections your node will maintain
  • default_protocol: The default protocol definition. This uses 'mesh' as the subnet and SSL encryption, as supplied by ssl_wrapper.py (in alpha releases this will use Plaintext)

Classes

mesh_socket

This peer-to-peer socket is the main purpose behind this library. It maintains a connection to a mesh network. Details on how it works specifically are outlined here, but the basics are outlined below.

It also inherits all the attributes of base_socket, though they are also outlined here

Constructor

mesh_socket(addr, port, prot=default_protocol, out_addr=None, debug_level=0)

  • addr: The address you’d like to bind to
  • port: The port you’d like to bind to
  • prot: The protocol you’d like to use
  • out_addr: Your outward-facing address, if that is different from (addr, port)
  • debug_level: The verbosity at which this and its associated mesh_daemon prints debug information
Variables
  • protocol: A protocol object which contains the subnet flag and the encryption method
  • debug_level: The verbosity of the socket with debug prints
  • routing_table: The current dict of peers in format {id: connection}
  • awaiting_ids: A list of connections awaiting a handshake
  • outgoing: A list of ids for outgoing connections
  • incoming: A list of ids for incoming connections
  • requests: A dict of the requests this node has made in format {request_id: delayed_message_contents}
  • waterfalls: A deque of metadata for recently received messages
  • queue: A deque of recently received messages
  • out_addr: A tuple which contains the outward facing address and port
  • id: This node’s SHA384-based id
  • daemon: This node’s mesh_daemon object
Methods
  • connect(addr, port, id=None): Connect to another mesh_socket (and assigns id if specified)
  • send(*args, type='broadcast'): Send a message to your peers with each argument as a packet
  • recv(quantity=1): Receive messages; If quantity != 1, returns a list of messages, otherwise returns one
  • handle_request(msg): Allows the daemon to parse subflag-level actions
  • waterfall(msg): Waterfalls a message to your peers

mesh_daemon

This inherits all the attributes of base_daemon, though they are also outlined here

Constructor

mesh_daemon(addr, port, server, prot=default_protocol)

  • addr: The address it should bind its incoming connection to
  • port: The port it should bind its incoming connection to
  • server: This daemon’s mesh_socket
  • prot: This daemon’s protocol
Variables
  • protocol: This daemon’s protocol object
  • server: A pointer to this daemon’s mesh_socket
  • sock: This daemon’s socket object
  • alive: A checker to shutdown the daemon. If False, its thread will stop running eventually.
  • exceptions: A list of unhandled Exceptions raised in mainloop
  • daemon: A Thread which runs through mainloop
Methods
  • mainloop(): The method through which daemon parses. This runs as long as alive is True, and alternately calls the collect_incoming_data methods of mesh_connections and handle_accept.
  • handle_accept(): Deals with incoming connections
  • disconnect(handler): Closes a given mesh_connection and removes its information from server
  • __print__(*args, level=None): Prints debug information if level >= server.debug_level

mesh_connection

This inherits all the attributes of base_connection, though they are also outlined here

Constructor

base_connection(sock, server, prot=default_protocol, outgoing=False)

  • sock: A socket.socket
  • server: This node’s mesh_socket
  • prot: This node’s protocol
  • outgoing: Whether or not this node is an outgoing connection
Variables
  • sock: This connection’s socket object
  • server: A pointer to this connection’s mesh_socket object
  • protocol: This connection’s protocol object
  • outgoing: A bool that states whether this connection is outgoing
  • buffer: A list of recently received characters
  • id: This node’s SHA384-based id
  • time: The time at which this node last received data
  • addr: This node’s outward-facing address
  • compression: A list of this node’s supported compression methods
  • last_sent: A copy of the most recently sent whisper or broadcast
  • expected: The number of bytes expected in the next message
  • active: A bool which says whether the next message is a size header, or a message (True if message)
Methods
  • fileno(): Returns sock’s file number
  • collect_incoming_data(data): Adds new data to the buffer
  • find_terminator(): Determines if a message has been fully received (name is a relic of when this had an end_of_tx flag)
  • found_terminator(): Deals with any data received when find_terminator returns True
  • send(msg_type, *args, id=server.id, time=base.getUTC()): Sends a message via sock
  • __print__(*args, level=None): Prints debug information if level >= server.debug_level

net.py

Deprecated. Scheduled to be removed in the next release.

ssl_wrapper.py

Variables

  • cleanup_files: Only present in python2; A list of files to clean up using the atexit module. Because of this setup, sudden crashes of Python will not clean up keys or certs.

Methods

  • generate_self_signed_cert(cert_file, key_file): Given two file-like objects, generate an SSL certificate and key file
  • get_socket(server_side): Returns an ssl.SSLSocket for use in other parts of this library
  • cleanup(): Only present in python2; Calls os.remove on all files in cleanup_files.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for py2p, version 0.3.186
Filename, size File type Python version Upload date Hashes
Filename, size py2p-0.3.186-py2.py3-none-any.whl (23.5 kB) File type Wheel Python version py2.py3 Upload date Hashes View
Filename, size py2p-0.3.186.tar.gz (18.5 kB) File type Source Python version None Upload date Hashes View
Filename, size py2p-0.3.186.zip (23.7 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page