Sphynx: Commenting API

Author: AlexisTM

docs/api.rst

@@ -0,0 +1,12 @@
+API
+==============
+
+.. automodule:: rawsocketpy
+   :members:
+
+.. automodule:: rawsocketpy.main
+   :members:
+
+
+
+

docs/index.rst

@@ -7,6 +7,7 @@ Welcome to RawSocketPy's documentation!
 
    installation
    quicktest
+   API
    raw_socket
    server_mode
 

docs/server_mode.rst

@@ -34,9 +34,9 @@ To a raw server, you have the following options:
        def setup(self):
            print("Begin") 
 
-
    def main():
        rs = RawAsyncServerCallback("wlp2s0", 0xEEFA, LongTaskTest, some_callback)
        rs.spin()
    if __name__ == '__main__':
        main()
+

rawsocketpy/__init__.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 """A Raw socket implementation allowing any ethernet type to be used/sniffed.
 
 .. moduleauthor:: Alexis Paques <alexis.paques@gmail.com>

rawsocketpy/asyncserver.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from .server import RawServer, RawServerCallback
 from gevent import pool, Greenlet
 

rawsocketpy/main.py

@@ -1,8 +1,11 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 import socket, select, struct, time
 from .util import get_hw, to_str, protocol_to_ethertype, to_bytes
 
 class RawPacket():
-    """RawPacket is the resulting data container. 
+    """RawPacket is the resulting data container of the RawSocket class. 
 
     It reads raw data and stores the MAC source, MAC destination, the Ethernet type and the data payload.
 
@@ -15,9 +18,17 @@ def __init__(self, data):
            foo (data): raw ethernet frame coming from the socket library, either **bytes in Python3** or **str in Python2**
         """
         self.dest = ""
+        """(str/bytes/bytearray): destination
+        """
         self.src = ""
+        """(str/bytes/bytearray): source
+        """
         self.type = ""
+        """(str/bytes/bytearray): ethertype
+        """
         self.data = ""
+        """ = (str/bytes/bytearray): payload received, aka the msg sent on the other side
+        """
         self.success = False
         try:
             self.dest, self.src, self.type = data[0:6], data[6:12], data[12:14]
@@ -34,6 +45,19 @@ def __str__(self):
         return "".join([self.__repr__(), ":\n", self.data.decode('utf-8')])
 
 class RawSocket(object):
+    """RawSocket is using the socket library to send raw ethernet frames, using socket.RAW_SOCK
+
+    It has a similar API to the socket library: send/recv/close/dup.
+
+    Args:
+       interface (str): the network interface to be used: wlp2s0, eth0, zt0, wlan0, ...
+       
+       protocol (int): the ethertype to use: 0xEEAF for example [0 to 65535]
+       
+       sock (socket.socket): If provided, this socket will be used for the communications
+       
+       no_recv_protocol (bool): If True, the socket will not receive any data, for "sending only" sockets.
+    """
     BROADCAST = "\xff\xff\xff\xff\xff\xff"
     def __init__(self, interface, protocol, sock=None, no_recv_protocol=False):
         if  not 0x0000 < protocol < 0xFFFF:
@@ -51,6 +75,8 @@ def __init__(self, interface, protocol, sock=None, no_recv_protocol=False):
         self.close = self.sock.close
 
     def dup(self):
+        """Duplicates the RawSocket
+        """
         return RawSocket(self.interface, self.non_processed_protocol, self.sock.dup(), self.no_recv_protocol)
 
     @staticmethod
@@ -61,12 +87,27 @@ def sock_create(interface, protocol, sock=None):
         return sock
 
     def send(self, msg, dest=None, ethertype=None):
+        """Sends data through the socket.
+
+        Args:
+           msg (str): Payload to be sent 
+           
+           dest (str/bytes/bytearray): recipient, if not mentioned it will be a broadcast example: "\xff\x12\x32\x34\x41" or bytes([255, 12, 32, 42, 43, 54])
+           
+           ethertype (str/bytes/bytearray): Allow to send data using a different ethertype using the same socket. Default is the protocol given in the constructor.
+        """
         if ethertype is None: ethertype = self.ethertype
         if dest is None: dest = self.BROADCAST
         payload = (to_bytes(dest) + self.mac + to_bytes(ethertype) +  to_bytes(msg))
         self.sock.send(payload)
 
     def recv(self):
+        """Receive data from the socket on the protocol provided in the constructor
+
+        Blocks until data arrives. A timeout can be implemented using the socket timeout.
+
+        Returns RawPacket
+        """
         data = self.sock.recv(1500)
         return RawPacket(data)
 

rawsocketpy/server.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 from .main import RawPacket, RawSocket
 from .util import get_hw, to_bytes, protocol_to_ethertype