varun-r-mallya/py-libp2p
1
0
Fork 0
mirror of https://github.com/varun-r-mallya/py-libp2p.git synced 2026-02-09 22:50:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Enforce pre-summary newline in docstrings

Browse Source
This commit is contained in:
Dominik Muhs
2019-10-24 20:10:45 +02:00
parent 87ed98d7af
commit bafdd8512d
52 changed files with 349 additions and 199 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
libp2p/pubsub/floodsub.py
View File

@ -31,35 +31,40 @@ class FloodSub(IPubsubRouter):
return self.protocols
def attach(self, pubsub: Pubsub) -> None:
"""Attach is invoked by the PubSub constructor to attach the router to
a freshly initialized PubSub instance.
"""
Attach is invoked by the PubSub constructor to attach the router to a
freshly initialized PubSub instance.
:param pubsub: pubsub instance to attach to
"""
self.pubsub = pubsub
def add_peer(self, peer_id: ID, protocol_id: TProtocol) -> None:
"""Notifies the router that a new peer has been connected.
"""
Notifies the router that a new peer has been connected.
:param peer_id: id of peer to add
"""
def remove_peer(self, peer_id: ID) -> None:
"""Notifies the router that a peer has been disconnected.
"""
Notifies the router that a peer has been disconnected.
:param peer_id: id of peer to remove
"""
async def handle_rpc(self, rpc: rpc_pb2.RPC, sender_peer_id: ID) -> None:
"""Invoked to process control messages in the RPC envelope. It is
invoked after subscriptions and payload messages have been processed.
"""
Invoked to process control messages in the RPC envelope. It is invoked
after subscriptions and payload messages have been processed.
:param rpc: rpc message
"""
async def publish(self, msg_forwarder: ID, pubsub_msg: rpc_pb2.Message) -> None:
"""Invoked to forward a new message that has been validated. This is
where the "flooding" part of floodsub happens.
"""
Invoked to forward a new message that has been validated. This is where
the "flooding" part of floodsub happens.
With flooding, routing is almost trivial: for each incoming message,
forward to all known peers in the topic. There is a bit of logic,
@ -87,15 +92,17 @@ class FloodSub(IPubsubRouter):
await stream.write(encode_varint_prefixed(rpc_msg.SerializeToString()))
async def join(self, topic: str) -> None:
"""Join notifies the router that we want to receive and forward
messages in a topic. It is invoked after the subscription announcement.
"""
Join notifies the router that we want to receive and forward messages
in a topic. It is invoked after the subscription announcement.
:param topic: topic to join
"""
async def leave(self, topic: str) -> None:
"""Leave notifies the router that we are no longer interested in a
topic. It is invoked after the unsubscription announcement.
"""
Leave notifies the router that we are no longer interested in a topic.
It is invoked after the unsubscription announcement.
:param topic: topic to leave
"""
@ -103,7 +110,8 @@ class FloodSub(IPubsubRouter):
def _get_peers_to_send(
self, topic_ids: Iterable[str], msg_forwarder: ID, origin: ID
) -> Iterable[ID]:
"""Get the eligible peers to send the data to.
"""
Get the eligible peers to send the data to.
:param msg_forwarder: peer ID of the peer who forwards the message to us.
:param origin: peer id of the peer the message originate from.

32
libp2p/pubsub/gossipsub.py
View File

@ -94,8 +94,9 @@ class GossipSub(IPubsubRouter):
return self.protocols
def attach(self, pubsub: Pubsub) -> None:
"""Attach is invoked by the PubSub constructor to attach the router to
a freshly initialized PubSub instance.
"""
Attach is invoked by the PubSub constructor to attach the router to a
freshly initialized PubSub instance.
:param pubsub: pubsub instance to attach to
"""
@ -108,7 +109,8 @@ class GossipSub(IPubsubRouter):
asyncio.ensure_future(self.heartbeat())
def add_peer(self, peer_id: ID, protocol_id: TProtocol) -> None:
"""Notifies the router that a new peer has been connected.
"""
Notifies the router that a new peer has been connected.
:param peer_id: id of peer to add
:param protocol_id: router protocol the peer speaks, e.g., floodsub, gossipsub
@ -129,7 +131,8 @@ class GossipSub(IPubsubRouter):
self.peers_to_protocol[peer_id] = protocol_id
def remove_peer(self, peer_id: ID) -> None:
"""Notifies the router that a peer has been disconnected.
"""
Notifies the router that a peer has been disconnected.
:param peer_id: id of peer to remove
"""
@ -144,8 +147,9 @@ class GossipSub(IPubsubRouter):
del self.peers_to_protocol[peer_id]
async def handle_rpc(self, rpc: rpc_pb2.RPC, sender_peer_id: ID) -> None:
"""Invoked to process control messages in the RPC envelope. It is
invoked after subscriptions and payload messages have been processed.
"""
Invoked to process control messages in the RPC envelope. It is invoked
after subscriptions and payload messages have been processed.
:param rpc: RPC message
:param sender_peer_id: id of the peer who sent the message
@ -189,7 +193,8 @@ class GossipSub(IPubsubRouter):
def _get_peers_to_send(
self, topic_ids: Iterable[str], msg_forwarder: ID, origin: ID
) -> Iterable[ID]:
"""Get the eligible peers to send the data to.
"""
Get the eligible peers to send the data to.
:param msg_forwarder: the peer id of the peer who forwards the message to me.
:param origin: peer id of the peer the message originate from.
@ -231,8 +236,9 @@ class GossipSub(IPubsubRouter):
async def join(self, topic: str) -> None:
# Note: the comments here are the near-exact algorithm description from the spec
"""Join notifies the router that we want to receive and forward
messages in a topic. It is invoked after the subscription announcement.
"""
Join notifies the router that we want to receive and forward messages
in a topic. It is invoked after the subscription announcement.
:param topic: topic to join
"""
@ -268,8 +274,9 @@ class GossipSub(IPubsubRouter):
async def leave(self, topic: str) -> None:
# Note: the comments here are the near-exact algorithm description from the spec
"""Leave notifies the router that we are no longer interested in a
topic. It is invoked after the unsubscription announcement.
"""
Leave notifies the router that we are no longer interested in a topic.
It is invoked after the unsubscription announcement.
:param topic: topic to leave
"""
@ -286,7 +293,8 @@ class GossipSub(IPubsubRouter):
# Heartbeat
async def heartbeat(self) -> None:
"""Call individual heartbeats.
"""
Call individual heartbeats.
Note: the heartbeats are called with awaits because each heartbeat depends on the
state changes in the preceding heartbeat

15
libp2p/pubsub/mcache.py
View File

@ -13,7 +13,8 @@ class CacheEntry:
"""
def __init__(self, mid: Tuple[bytes, bytes], topics: Sequence[str]) -> None:
"""Constructor.
"""
Constructor.
:param mid: (seqno, from_id) of the msg
:param topics: list of topics this message was sent on
@ -32,7 +33,8 @@ class MessageCache:
history: List[List[CacheEntry]]
def __init__(self, window_size: int, history_size: int) -> None:
"""Constructor.
"""
Constructor.
:param window_size: Size of the window desired.
:param history_size: Size of the history desired.
@ -49,7 +51,8 @@ class MessageCache:
self.history = [[] for _ in range(history_size)]
def put(self, msg: rpc_pb2.Message) -> None:
"""Put a message into the mcache.
"""
Put a message into the mcache.
:param msg: The rpc message to put in. Should contain seqno and from_id
"""
@ -59,7 +62,8 @@ class MessageCache:
self.history[0].append(CacheEntry(mid, msg.topicIDs))
def get(self, mid: Tuple[bytes, bytes]) -> Optional[rpc_pb2.Message]:
"""Get a message from the mcache.
"""
Get a message from the mcache.
:param mid: (seqno, from_id) of the message to get.
:return: The rpc message associated with this mid
@ -70,7 +74,8 @@ class MessageCache:
return None
def window(self, topic: str) -> List[Tuple[bytes, bytes]]:
"""Get the window for this topic.
"""
Get the window for this topic.
:param topic: Topic whose message ids we desire.
:return: List of mids in the current window.

46
libp2p/pubsub/pubsub.py
View File

@ -81,7 +81,8 @@ class Pubsub:
def __init__(
self, host: IHost, router: "IPubsubRouter", my_id: ID, cache_size: int = None
) -> None:
"""Construct a new Pubsub object, which is responsible for handling all
"""
Construct a new Pubsub object, which is responsible for handling all
Pubsub-related messages and relaying messages as appropriate to the
Pubsub router (which is responsible for choosing who to send messages
to).
@ -148,8 +149,9 @@ class Pubsub:
return packet
async def continuously_read_stream(self, stream: INetStream) -> None:
"""Read from input stream in an infinite loop. Process messages from
other nodes.
"""
Read from input stream in an infinite loop. Process messages from other
nodes.
:param stream: stream to continously read from
"""
@ -207,8 +209,9 @@ class Pubsub:
def set_topic_validator(
self, topic: str, validator: ValidatorFn, is_async_validator: bool
) -> None:
"""Register a validator under the given topic. One topic can only have
one validtor.
"""
Register a validator under the given topic. One topic can only have one
validtor.
:param topic: the topic to register validator under
:param validator: the validator used to validate messages published to the topic
@ -217,7 +220,8 @@ class Pubsub:
self.topic_validators[topic] = TopicValidator(validator, is_async_validator)
def remove_topic_validator(self, topic: str) -> None:
"""Remove the validator from the given topic.
"""
Remove the validator from the given topic.
:param topic: the topic to remove validator from
"""
@ -225,7 +229,8 @@ class Pubsub:
del self.topic_validators[topic]
def get_msg_validators(self, msg: rpc_pb2.Message) -> Tuple[TopicValidator, ...]:
"""Get all validators corresponding to the topics in the message.
"""
Get all validators corresponding to the topics in the message.
:param msg: the message published to the topic
"""
@ -236,7 +241,8 @@ class Pubsub:
)
async def stream_handler(self, stream: INetStream) -> None:
"""Stream handler for pubsub. Gets invoked whenever a new stream is
"""
Stream handler for pubsub. Gets invoked whenever a new stream is
created on one of the supported pubsub protocols.
:param stream: newly created stream
@ -291,7 +297,8 @@ class Pubsub:
def handle_subscription(
self, origin_id: ID, sub_message: rpc_pb2.RPC.SubOpts
) -> None:
"""Handle an incoming subscription message from a peer. Update internal
"""
Handle an incoming subscription message from a peer. Update internal
mapping to mark the peer as subscribed or unsubscribed to topics as
defined in the subscription message.
@ -311,7 +318,8 @@ class Pubsub:
# FIXME(mhchia): Change the function name?
async def handle_talk(self, publish_message: rpc_pb2.Message) -> None:
"""Put incoming message from a peer onto my blocking queue.
"""
Put incoming message from a peer onto my blocking queue.
:param publish_message: RPC.Message format
"""
@ -325,7 +333,8 @@ class Pubsub:
await self.my_topics[topic].put(publish_message)
async def subscribe(self, topic_id: str) -> "asyncio.Queue[rpc_pb2.Message]":
"""Subscribe ourself to a topic.
"""
Subscribe ourself to a topic.
:param topic_id: topic_id to subscribe to
"""
@ -355,7 +364,8 @@ class Pubsub:
return self.my_topics[topic_id]
async def unsubscribe(self, topic_id: str) -> None:
"""Unsubscribe ourself from a topic.
"""
Unsubscribe ourself from a topic.
:param topic_id: topic_id to unsubscribe from
"""
@ -381,7 +391,8 @@ class Pubsub:
await self.router.leave(topic_id)
async def message_all_peers(self, raw_msg: bytes) -> None:
"""Broadcast a message to peers.
"""
Broadcast a message to peers.
:param raw_msg: raw contents of the message to broadcast
"""
@ -392,7 +403,8 @@ class Pubsub:
await stream.write(encode_varint_prefixed(raw_msg))
async def publish(self, topic_id: str, data: bytes) -> None:
"""Publish data to a topic.
"""
Publish data to a topic.
:param topic_id: topic which we are going to publish the data to
:param data: data which we are publishing
@ -412,7 +424,8 @@ class Pubsub:
logger.debug("successfully published message %s", msg)
async def validate_msg(self, msg_forwarder: ID, msg: rpc_pb2.Message) -> None:
"""Validate the received message.
"""
Validate the received message.
:param msg_forwarder: the peer who forward us the message.
:param msg: the message.
@ -441,7 +454,8 @@ class Pubsub:
raise ValidationError(f"Validation failed for msg={msg}")
async def push_msg(self, msg_forwarder: ID, msg: rpc_pb2.Message) -> None:
"""Push a pubsub message to others.
"""
Push a pubsub message to others.
:param msg_forwarder: the peer who forward us the message.
:param msg: the message we are going to push out.

7
libp2p/pubsub/pubsub_notifee.py
View File

@ -30,9 +30,10 @@ class PubsubNotifee(INotifee):
pass
async def connected(self, network: INetwork, conn: INetConn) -> None:
"""Add peer_id to initiator_peers_queue, so that this peer_id can be
used to create a stream and we only want to have one pubsub stream with
each peer.
"""
Add peer_id to initiator_peers_queue, so that this peer_id can be used
to create a stream and we only want to have one pubsub stream with each
peer.
:param network: network the connection was opened on
:param conn: connection that was opened

24
libp2p/pubsub/pubsub_router_interface.py
View File

@ -19,22 +19,25 @@ class IPubsubRouter(ABC):
@abstractmethod
def attach(self, pubsub: "Pubsub") -> None:
"""Attach is invoked by the PubSub constructor to attach the router to
a freshly initialized PubSub instance.
"""
Attach is invoked by the PubSub constructor to attach the router to a
freshly initialized PubSub instance.
:param pubsub: pubsub instance to attach to
"""
@abstractmethod
def add_peer(self, peer_id: ID, protocol_id: TProtocol) -> None:
"""Notifies the router that a new peer has been connected.
"""
Notifies the router that a new peer has been connected.
:param peer_id: id of peer to add
"""
@abstractmethod
def remove_peer(self, peer_id: ID) -> None:
"""Notifies the router that a peer has been disconnected.
"""
Notifies the router that a peer has been disconnected.
:param peer_id: id of peer to remove
"""
@ -53,7 +56,8 @@ class IPubsubRouter(ABC):
# FIXME: Should be changed to type 'peer.ID'
@abstractmethod
async def publish(self, msg_forwarder: ID, pubsub_msg: rpc_pb2.Message) -> None:
"""Invoked to forward a new message that has been validated.
"""
Invoked to forward a new message that has been validated.
:param msg_forwarder: peer_id of message sender
:param pubsub_msg: pubsub message to forward
@ -61,16 +65,18 @@ class IPubsubRouter(ABC):
@abstractmethod
async def join(self, topic: str) -> None:
"""Join notifies the router that we want to receive and forward
messages in a topic. It is invoked after the subscription announcement.
"""
Join notifies the router that we want to receive and forward messages
in a topic. It is invoked after the subscription announcement.
:param topic: topic to join
"""
@abstractmethod
async def leave(self, topic: str) -> None:
"""Leave notifies the router that we are no longer interested in a
topic. It is invoked after the unsubscription announcement.
"""
Leave notifies the router that we are no longer interested in a topic.
It is invoked after the unsubscription announcement.
:param topic: topic to leave
"""

3
libp2p/pubsub/validators.py
View File

@ -1,6 +1,7 @@
# FIXME: Replace the type of `pubkey` with a custom type `Pubkey`
def signature_validator(pubkey: bytes, msg: bytes) -> bool:
"""Verify the message against the given public key.
"""
Verify the message against the given public key.
:param pubkey: the public key which signs the message.
:param msg: the message signed.