Docs: Full API documentation

Author: AlexisTM

.gitignore

@@ -104,3 +104,4 @@ venv.bak/
 .mypy_cache/
 .idea
 */.vscode*
+.vscode*

rawsocketpy/__init__.py

@@ -3,9 +3,11 @@
 
 """A Raw socket implementation allowing any ethernet type to be used/sniffed.
 
-.. moduleauthor:: Alexis Paques <alexis.paques@gmail.com>
+If gevent is available, sockets are monkey patched and two additionnal asynchronous server implementations are available: :class:`RawAsyncServer`, :class:`RawAsyncServerCallback` 
 
+.. moduleauthor:: Alexis Paques <alexis.paques@gmail.com>
 """
+
 from __future__ import print_function
 try:
     from gevent import monkey; monkey.patch_all()
@@ -14,5 +16,6 @@
     print("Gevent could not be loaded; the sockets will not be cooperative.")
 
 from .util import get_hw, protocol_to_ethertype, to_bytes, to_str
-from .main import RawPacket, RawSocket
+from .socket import RawSocket
+from .packet import RawPacket
 from .server import RawServer, RawRequestHandler, RawServerCallback

rawsocketpy/asyncserver.py

@@ -5,10 +5,27 @@
 from gevent import pool, Greenlet
 
 class RawAsyncServer(RawServer):
+    """
+    Prefered server instead of RawServer.
+    Async server using :class:`gevent.Greenlet` in a :class:`gevent.pool` to allow asynchronous calls.
+
+    This will ensure you are not loosing data because the handler is too long.
+    """
     pool = pool.Pool()
     def handle_handler(self, handler):
+        """Add the Greenlet to the pool with ``handler.run()``, the function to run.
+        
+        :param handler: The RawRequestHandler provided in the constructor
+        :type handler: RawRequestHandler"""
         self.pool.start(Greenlet(handler.run))
 
 class RawAsyncServerCallback(RawServerCallback, RawAsyncServer):
+    """
+    Async server using :class:`gevent.Greenlet` in a :class:`gevent.pool` to allow asynchronous calls.
+    """
     def handle_handler(self, handler):
+        """Add the Greenlet to the pool with ``self.callback(handler, self)``: the function to run.
+        
+        :param handler: The RawRequestHandler provided in the constructor
+        :type handler: RawRequestHandler"""
         self.pool.start(Greenlet(self.callback, handler, self))

rawsocketpy/main.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from .util import to_str, to_bytes
+
+class RawPacket():
+    """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.
+
+    RawPacket.success is true if the packet is successfuly read.
+    """
+    def __init__(self, data):
+        """A really simple class.
+
+        :param data: raw ethernet II frame coming from the socket library, either **bytes in Python3** or **str in Python2**
+        :type data: str/bytes/bytearray
+        """
+        self.dest = ""
+        """:description: Destination MAC address
+        :type: str/bytes/bytearray"""
+        self.src = ""
+        """:description: Source MAC address
+        :type: str/bytes/bytearray"""
+        self.type = ""
+        """:description: Ethertype
+        :type: str/bytes/bytearray"""
+        self.data = ""
+        """:description: Payload received
+        :type: str/bytes/bytearray"""
+        self.success = False
+        """:description: True if the packet has been successfully unmarshalled 
+        :type: bool"""
+        try:
+            self.dest, self.src, self.type = data[0:6], data[6:12], data[12:14]
+            self.data = data[14:]
+            self.success = True
+        except Exception as e:
+            print("rawsocket: ", e)
+            self.success = False
+
+    def __repr__(self):
+        return "".join([to_str(self.src), " == 0x", to_str(self.type, separator=""), " => ", to_str(self.dest), " - ", "OK" if self.success else "FAILED"])
+
+    def __str__(self):
+        return "".join([self.__repr__(), ":\n", self.data.decode('utf-8')])

rawsocketpy/packet.py

@@ -1,55 +1,113 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-from .main import RawPacket, RawSocket
+from .packet import RawPacket
+from .socket import RawSocket
 from .util import get_hw, to_bytes, protocol_to_ethertype
 
 class RawServer(object):
+    """A **Blocking** base server implementation of a server on top of the RawSocket.
+    It waits for data, encapsulate the data in the RequestHandlerClass provided and blocks until the RequestHandlerClass run() function finishes.  
+
+    :note: packet = recv() 
+           -> RequestHandlerClass(packet) 
+           -> RequestHandlerClass.run()
+           -> loop
+    """
     def __init__(self, interface, protocol, RequestHandlerClass):
+        """
+
+        :param interface: interface to be used.
+        :type interface: str
+        :param protocol: Ethernet II protocol, RawSocket [1536-65535]
+        :type protocol: int
+        :param RequestHandlerClass: The class that will handle the requests
+        :type RequestHandlerClass: RawServerCallback
+        """
         self.RequestHandlerClass = RequestHandlerClass
         self.socket = RawSocket(interface, protocol)
         self.recv = self.socket.recv
         self.running = False
 
     def spin_once(self):
+        """Handles the next message"""
         packet = self.recv()
         handler = self.RequestHandlerClass(packet, self)
         self.handle_handler(handler)
 
     def handle_handler(self, handler):
+        """Manage the handler, can be overwritten"""
         handler.run()
 
     def spin(self):
+        """Loops until self.running becomes False (from a Request Handler or another thread/coroutine)"""
         self.running = True
         while self.running:
             self.spin_once()
 
 
 class RawServerCallback(RawServer):
+    """A blocking server implementation that uses a centralized callback. This is useful for a stateful server.
+
+    :note: packet = recv() 
+           -> RequestHandlerClass(packet, self) 
+           -> callback(RequestHandlerClass, self)
+           -> loop
+    """
     def __init__(self, interface, protocol, RequestHandlerClass, callback):
+        """
+        :param interface: interface to be used.
+        :type interface: str
+        :param protocol: Ethernet II protocol, RawSocket [1536-65535]
+        :type protocol: int
+        :param RequestHandlerClass: The class that will handle the requests
+        :type RequestHandlerClass: RawServerCallback
+        :param callback: callback to be used.
+        :type callback: function
+        """
         self.callback = callback
         RawServer.__init__(self, interface, protocol, RequestHandlerClass)
 
     def handle_handler(self, handler):
+        """
+        Overwritten: Calls callback(handler, self) instead.
+        """
         self.callback(handler, self)
 
 
 class RawRequestHandler(object):
+    """The class that handles the request. 
+    It has access to the packet and the server data.
+    """
     def __init__(self, packet, server):
         self.packet = packet
+        """:description: Packet received
+        :type: RawPacket"""
         self.server = server
-        # self.server.socket.sock = low level socket
+        """:description: Server from which the packet comes
+        :type: RawServer"""
 
     def finish(self):
+        """empty: To be **overwritten**"""
         pass
 
     def setup(self):
+        """empty: To be **overwritten**"""
         pass
 
     def handle(self):
-        print(self.packet)
+        """empty: To be **overwritten**"""
+        pass
 
     def run(self):
+        """Run the request handling process: 
+
+        try:
+            * self.setup()
+            * self.handle()
+        finally:
+            * self.finish()
+        """
         try:
             self.setup()
             self.handle()