API Reference¶
Environment¶
All of the following are environment variables that can be set to configure net. Each variable is prefixed with “NET_{value}”.
Network Thread Limit¶
-
net.
THREAD_LIMIT
¶
Default: 5
For larger networks, you may want to increase the thread count. By default, this is set to 5. When scanning the network for peers, the total number of hosts is load balanced between the thread count you provide in this variable.
Port Configuration¶
-
net.
PORT_START
¶
Default: 3010
This is the starting port that the peers will attempt to bind to.
-
net.
PORT_RANGE
¶
Default: 5
This is the range of ports that you want the port to try to bind to. If the default is 3010, net will scan 3010 - 3015 for a port.
Peer Configuration¶
-
net.
GROUP
¶
Default: None
You can group your peers together by defining the group it belongs to. This helps Peers find compatible peers or collections.
-
net.
IS_HUB
¶
Default: False
If you have a single peer that should be the center of an application, you can
identify it through this variable. When you run net.info
on a peer with this
flag, it will return True in the hub field of the friendly_id.
Decorators¶
-
net.
connect
(tag=None)[source]¶ Registers a function as a connection. This will be tagged and registered with the Peer server. The tag is a base64 encoded path to the function or can be manually tagged with the tag parameter. Tagging a named function allows you to interconnect functions between code bases.
For example, a connected function with no tag is tied to the
func.__module__
+func.__name__
. This means the peers will only know which functions are compatible based on the namespace staying the same.# app version 1 running on PeerA app/ module/ function # app version 2 running on PeerB app/ module/ function2 <- # renamed from function
In the above example, PeerA could make a request to PeerB to execute “app.module.function”. But that function no longer exists as far as PeerB is concerned. The source code and functionality could be exactly the same, but the logical location is different and therefore will fail.
# app version 1 running on PeerA app/ module/ function (tagged: "MyTaggedFunction") # app version 2 running on PeerB app/ module/ function2 (tagged: "MyTaggedFunction")
In the above example, we have tagged function and function2 with the same tag, “MyTaggedFunction”. Now when PeerA requests to execute, it will request that PeerB executes “MyTaggedFunction” which is attached to the new renamed function.
Standard no tagging
@net.connect() def your_function(some_value): return some_value
Custom tagging
@net.connect("MyTaggedFunction") def your_function(some_value): return some_value
-
net.
subscribe
(event, peers=None)[source]¶ Subscribe to an event on another peer or set of peers. When the peer triggers an event using
net.event
, the peer will take the arguments passed and forward them to this function. By default, this will subscribe to all peers. You can also manually filter the peers by selectively passing in only the peers you want to subscribe to using thepeers
keyword argument.Subscribe to “some_event” on group1 peers only.
group1_peers = net.peers(groups=['group1']) @net.subscribe("some_event", group1_peers) def your_function(subscription_args, subscription_kwarg=None): return some_value
Subscribe to “some_event” on a single peer.
peer = net.peers()[0] @net.subscribe("some_event", peer) def your_function(subscription_args, subscription_kwarg=None): return some_value
Subscribe to “some_event” on all peers.
@net.subscribe("some_event") def your_function(subscription_args, subscription_kwarg=None): return some_value
Functions¶
These functions are in place to help with discovering the network and interacting with other peers.
-
net.
peers
(refresh=False, groups=None)[source]¶ Get a list of all peers on your network. This is a cached values since the call to graph the network can be long.
The initial call to this will hang for a few seconds. Under the hood, it is making a shell call to
arp -a
which will walk your network and find all hosts.Standard call to get the peers on your network.
all_peers = net.peers()
Refresh all peers in the cache
all_peers = net.peers(refresh=True)
Refresh the cache with peers in group1
all_peers = net.peers("group1", refresh=True)
Parameters: - refresh – Bool
- groups – str
Returns:
Defaults¶
These are prebuilt flags and handlers for helping get information about peers and the data flow between peers.
Peer¶
Each instance of python will be assigned a Peer singleton. This is not a true
singleton for development and testing purposes. Although, for production, always
access the peer using the net.Peer()
call. The first thing to understand is
that net.Peer()
is referring to the Peer running in the current instance of
python. So, if you are writing a connection and inside that connection you call
net.Peer()
. Depending on if that function is being run locally or remotely
will determine which peer you are being returned.
-
net.
Peer
(*args, **kwargs)[source]¶ Running Peer server for this instance of python.
Returns: net.peer._Peer
-
class
net.peer.
_Peer
(launch=True, test=False, group=None)[source]¶ -
CONNECTIONS
= {b'bmV0LmRlZmF1bHRzLmhhbmRsZXJzLm51bGw=': <function null>, b'bmV0LmRlZmF1bHRzLmhhbmRsZXJzLmluZm8=': <function info>, b'bmV0LmRlZmF1bHRzLmhhbmRsZXJzLnBhc3NfdGhyb3VnaA==': <function pass_through>, b'bmV0LmRlZmF1bHRzLmhhbmRsZXJzLnN1YnNjcmlwdGlvbl9oYW5kbGVy': <function subscription_handler>}¶
-
SUBSCRIPTIONS
= {}¶
-
FLAGS
= {b'SU5WQUxJRF9DT05ORUNUSU9O': <function invalid_connection>, b'TlVMTA==': <function null_response>}¶
-
static
decode
(byte_string)[source]¶ Decode a byte string sent from a peer.
Parameters: byte_string – base64 Returns: str
-
classmethod
decode_id
(id)[source]¶ Decode a peer id
Parameters: id – base64 Returns: dict {‘group’: str, ‘host’: str, ‘port’: int }
-
classmethod
encode
(obj)[source]¶ Encode an object for delivery.
Parameters: obj – JSON compatible types Returns: str
-
friendly_id
¶ Get the peers id in a friendly displayable way.
Returns: str
-
static
generate_id
(port, host, group=None)[source]¶ Generate a peers id.
Parameters: - port – int
- host – str
- group – str
Returns: base64
-
host
¶ Host that the peer is running on.
Returns: str
-
hub
¶ Defines if this peer acts as the hub for communication through the network.
Returns: bool
-
id
¶ Get this peers id. This is tethered to the port and the executable path the peer was launched with. This is base64 encoded for easier delivery.
Returns: base64
-
port
¶ Port that the peer is running on.
Returns: int
-