kademlia package

The best place to start is the examples folder before diving into the API.

kademlia.crawling module

class kademlia.crawling.NodeSpiderCrawl(protocol, node, peers, ksize, alpha)

Bases: SpiderCrawl

Create a new C{SpiderCrawl}er.

Parameters:

• protocol – A KademliaProtocol instance.

• node – A Node representing the key we’re looking for

• peers – A list of Node instances that provide the entry point for the network

• ksize – The value for k based on the paper

• alpha – The value for alpha based on the paper

async find()

Find the closest nodes.

class kademlia.crawling.RPCFindResponse(response)

Bases: object

A wrapper for the result of a RPC find.

Parameters:

response – This will be a tuple of (<response received>, <value>) where <value> will be a list of tuples if not found or a dictionary of {‘value’: v} where v is the value desired

get_node_list()

Get the node list in the response. If there’s no value, this should be set.

get_value()

happened()

Did the other host actually respond?

has_value()

class kademlia.crawling.SpiderCrawl(protocol, node, peers, ksize, alpha)

Bases: object

Crawl the network and look for given 160-bit keys.

Create a new C{SpiderCrawl}er.

Parameters:

• protocol – A KademliaProtocol instance.

• node – A Node representing the key we’re looking for

• peers – A list of Node instances that provide the entry point for the network

• ksize – The value for k based on the paper

• alpha – The value for alpha based on the paper

class kademlia.crawling.ValueSpiderCrawl(protocol, node, peers, ksize, alpha)

Bases: SpiderCrawl

Create a new C{SpiderCrawl}er.

Parameters:

• protocol – A KademliaProtocol instance.

• node – A Node representing the key we’re looking for

• peers – A list of Node instances that provide the entry point for the network

• ksize – The value for k based on the paper

• alpha – The value for alpha based on the paper

async find()

Find either the closest nodes or the value requested.

kademlia.network module

kademlia.node module

class kademlia.node.Node(node_id, ip=None, port=None)

Bases: object

Simple object to encapsulate the concept of a Node (minimally an ID, but also possibly an IP and port if this represents a node on the network). This class should generally not be instantiated directly, as it is a low level construct mostly used by the router.

Create a Node instance.

Parameters:

• node_id (int) – A value between 0 and 2^160

• ip (string) – Optional IP address where this Node lives

• port (int) – Optional port for this Node (set when IP is set)

distance_to(node)

Get the distance between this node and another.

same_home_as(node)

class kademlia.node.NodeHeap(node, maxsize)

Bases: object

A heap of nodes ordered by distance to a given node.

Constructor.

@param node: The node to measure all distnaces from. @param maxsize: The maximum size that this heap can grow to.

get_ids()

get_node(node_id)

get_uncontacted()

have_contacted_all()

mark_contacted(node)

popleft()

push(nodes)

Push nodes onto heap.

@param nodes: This can be a single item or a C{list}.

remove(peers)

Remove a list of peer ids from this heap. Note that while this heap retains a constant visible size (based on the iterator), it’s actual size may be quite a bit larger than what’s exposed. Therefore, removal of nodes may not change the visible size as previously added nodes suddenly become visible.

kademlia.protocol module

kademlia.routing module

class kademlia.routing.KBucket(rangeLower, rangeUpper, ksize, replacementNodeFactor=5)

Bases: object

add_node(node)

Add a C{Node} to the C{KBucket}. Return True if successful, False if the bucket is full.

If the bucket is full, keep track of node in a replacement list, per section 4.1 of the paper.

depth()

get_nodes()

has_in_range(node)

head()

is_new_node(node)

remove_node(node)

split()

touch_last_updated()

class kademlia.routing.RoutingTable(protocol, ksize, node)

Bases: object

@param node: The node that represents this server. It won’t be added to the routing table, but will be needed later to determine which buckets to split or not.

add_contact(node)

find_neighbors(node, k=None, exclude=None)

flush()

get_bucket_for(node)

Get the index of the bucket that the given node would fall into.

is_new_node(node)

lonely_buckets()

Get all of the buckets that haven’t been updated in over an hour.

remove_contact(node)

split_bucket(index)

class kademlia.routing.TableTraverser(table, startNode)

Bases: object

kademlia.storage module

class kademlia.storage.ForgetfulStorage(ttl=604800)

Bases: IStorage

By default, max age is a week.

__getitem__(key)

Get the given key. If item doesn’t exist, raises C{KeyError}

__setitem__(key, value)

Set a key to the given value.

cull()

get(key, default=None)

Get given key. If not found, return default.

iter_older_than(seconds_old)

Return the an iterator over (key, value) tuples for items older than the given secondsOld.

class kademlia.storage.IStorage

Bases: ABC

Local storage for this node. IStorage implementations of get must return the same type as put in by set

abstract __getitem__(key)

Get the given key. If item doesn’t exist, raises C{KeyError}

abstract __setitem__(key, value)

Set a key to the given value.

abstract get(key, default=None)

Get given key. If not found, return default.

abstract iter_older_than(seconds_old)

Return the an iterator over (key, value) tuples for items older than the given secondsOld.

kademlia.utils module

General catchall for functions that don’t make sense as methods.

kademlia.utils.bytes_to_bit_string(bites)

kademlia.utils.digest(string)

async kademlia.utils.gather_dict(dic)

kademlia.utils.shared_prefix(args)

Find the shared prefix between the strings.

For instance:

sharedPrefix([‘blahblah’, ‘blahwhat’])

returns ‘blah’.