Initial tcp_socket implementation

__init__.py

@@ -0,0 +1,435 @@
+#!/usr/bin/env python
+# -*- coding: UTF-8 -*-
+
+"""
+tcp_socket (TCP Socket)
+=======================
+
+**Author:**
+
+* Dirk Alders <sudo-dirk@mount-mockery.de>
+
+**Description:**
+
+    This Module supports a client/ server tcp socket connection.
+
+**Submodules:**
+
+* :class:`tcp_socket.tcp_client`
+* :class:`tcp_socket.tcp_client_stp`
+* :class:`tcp_socket.tcp_server`
+* :class:`tcp_socket.tcp_server_stp`
+
+**Unittest:**
+
+        See also the :download:`unittest <../../tcp_socket/_testresults_/unittest.pdf>` documentation.
+"""
+__DEPENDENCIES__ = ['stringtools', 'task', ]
+
+import stringtools
+import task
+
+import logging
+import socket
+import time
+
+logger_name = 'TCP_SOCKET'
+logger = logging.getLogger(logger_name)
+
+
+class tcp_base(object):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+    :param rx_log_lvl: The log level to log incomming RX-data
+    :type rx_log_lvl: int
+
+    This is the base class for other classes in this module.
+
+    .. note:: This class is not designed for direct usage.
+    """
+    LOG_PREFIX = 'TCP_IP:'
+    RX_LENGTH = 0xff
+    COM_TIMEOUT = 0.5
+
+    def __init__(self, host, port, rx_log_lvl=logging.INFO):
+        self.host = host
+        self.port = port
+        self.__socket__ = None
+        self.__data_available_callback__ = None
+        self.__supress_data_available_callback__ = False
+        self.__connect_callback__ = None
+        self.__disconnect_callback__ = None
+        self.__clean_receive_buffer__()
+        self.__connection__ = None
+        self.__listening_message_displayed__ = False
+        self.__client_address__ = None
+        self.__queue__ = task.threaded_queue()
+        self.__queue__.enqueue(5, self.__receive_task__, rx_log_lvl)
+        self.__queue__.run()
+
+    def client_address(self):
+        """
+        :return: The client address.
+        :rtype: str
+
+        This method returns the address of the connected client.
+        """
+        return self.__client_address__[0]
+
+    def receive(self, timeout=1, num=None):
+        """
+        :param timeout: The timeout for receiving data (at least after the timeout the method returns data or None).
+        :type timeout: float
+        :param num: the number of bytes to receive (use None to get all available data).
+        :type num: int
+        :return: The received data.
+        :rtype: str
+
+        This method returns data received via the initiated communication channel.
+        """
+        rv = None
+        if self.__connection__ is not None:
+            tm = time.time()
+            while (num is not None and len(self.__receive_buffer__) < num) or (num is None and len(self.__receive_buffer__) < 1):
+                if self.__connection__ is None:
+                    return None
+                if time.time() > tm + timeout:
+                    logger.warning('%s TIMEOUT (%ss): Not enough data in buffer. Requested %s and buffer size is %d.', self.LOG_PREFIX, repr(timeout), repr(num or 'all'), len(self.__receive_buffer__))
+                    return None
+                time.sleep(0.05)
+            if num is None:
+                rv = self.__receive_buffer__
+                self.__clean_receive_buffer__()
+            else:
+                rv = self.__receive_buffer__[:num]
+                self.__receive_buffer__ = self.__receive_buffer__[num:]
+        return rv
+
+    def send(self, data, timeout=1, log_lvl=logging.INFO):
+        """
+        :param data: The data to be send over the communication channel.
+        :type data: str
+        :param timeout: The timeout for sending data (e.g. time to establish new connection).
+        :type timeout: float
+        :param rx_log_lvl: The log level to log outgoing TX-data
+        :type rx_log_lvl: int
+        :return: True if data had been sent, otherwise False.
+        :rtype: bool
+
+        This method sends data via the initiated communication channel.
+        """
+        cnt = 0
+        while self.__connection__ is None and cnt < int(10 * timeout):
+            time.sleep(.1)  # give some time to establish the connection
+            cnt += 1
+        if self.__connection__ is not None:
+            self.__connection__.sendall(data)
+            logger.log(log_lvl, '%s TX -> "%s"', self.LOG_PREFIX, stringtools.hexlify(data))
+            return True
+        else:
+            logger.warning('%s Cound NOT send -> "%s"', self.LOG_PREFIX, stringtools.hexlify(data))
+            return False
+
+    def register_callback(self, callback):
+        """
+        :param callback: The callback which will be executed, when data is available.
+        :type callback: function
+
+        This method sets the callback which is executed, if data is available. You need to execute :func:`receive` of the instance
+        given with the first argument.
+
+        .. note:: The :func:`callback` is executed with these arguments:
+
+            :param self: This communication instance
+        """
+        self.__data_available_callback__ = callback
+
+    def register_connect_callback(self, callback):
+        """
+        :param callback: The callback which will be executed, when a connect is identified.
+        :type callback: function
+
+        This method sets the callback which is executed, if a connect is identified.
+        """
+        self.__connect_callback__ = callback
+
+    def register_disconnect_callback(self, callback):
+        """
+        :param callback: The callback which will be executed, when a disconnect is identified.
+        :type callback: function
+
+        This method sets the callback which is executed, if a disconnect is identified.
+        """
+        self.__disconnect_callback__ = callback
+
+    def __receive_task__(self, queue_inst, rx_log_lvl):
+        if self.__connection__ is not None:
+            try:
+                data = self.__connection__.recv(self.RX_LENGTH)
+            except socket.error as e:
+                if e.errno != 11:
+                    raise
+                else:
+                    time.sleep(.05)
+            else:
+                if len(data) > 0:
+                    logger.log(rx_log_lvl, '%s RX <- "%s"', self.LOG_PREFIX, stringtools.hexlify(data))
+                    self.__receive_buffer__ += data
+                else:
+                    self.__connection_lost__()
+            self.__call_data_available_callback__()
+        else:
+            self.__connect__()
+        queue_inst.enqueue(5, self.__receive_task__, rx_log_lvl)
+
+    def __call_data_available_callback__(self):
+        if len(self.__receive_buffer__) > 0 and not self.__supress_data_available_callback__ and self.__data_available_callback__ is not None:
+            self.__supress_data_available_callback__ = True
+            self.__data_available_callback__(self)
+            self.__supress_data_available_callback__ = False
+
+    def __connection_lost__(self):
+        self.__listening_message_displayed__ = False
+        self.__connection__.close()
+        self.__connection__ = None
+        self.__client_address__ = None
+        logger.info('%s Connection lost...', self.LOG_PREFIX)
+        if self.__disconnect_callback__ is not None:
+            self.__disconnect_callback__()
+
+    def __clean_receive_buffer__(self):
+        logger.debug("%s Cleaning up receive-buffer", self.LOG_PREFIX)
+        self.__receive_buffer__ = ""
+
+    def close(self):
+        """
+        This method closes the active communication channel, if channel exists.
+        """
+        self.__queue__.stop()
+        self.__queue__.join()
+        if self.__connection__ is not None:
+            self.__connection_lost__()
+        if self.__socket__ is not None:
+            self.__socket__.close()
+
+    def __del__(self):
+        self.close()
+
+
+class tcp_server(tcp_base):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+    :param rx_log_lvl: The log level to log incomming RX-data
+    :type rx_log_lvl: int
+
+    This class supports a tcp-server transfering a serial stream of bytes (characters).
+
+    .. note:: You need a :class:`tcp_client` to communicate with the server.
+
+    **Example:**
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server.py
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server.log
+    """
+    def __connect__(self):
+        if self.__socket__ is None:
+            # Create a TCP/IP socket
+            self.__socket__ = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            # Bind the socket to the port
+            server_address = (self.host, self.port)
+            self.__socket__.bind(server_address)
+            # Listen for incoming connections
+            self.__socket__.listen(1)
+            self.__socket__.settimeout(self.COM_TIMEOUT)
+            self.__socket__.setblocking(False)
+        if not self.__listening_message_displayed__:
+            logger.info('%s Server listening to %s:%d', self.LOG_PREFIX, self.host, self.port)
+            self.__listening_message_displayed__ = True
+        try:
+            self.__connection__, self.__client_address__ = self.__socket__.accept()
+        except socket.error as e:
+            if e.errno != 11:
+                raise
+            else:
+                time.sleep(.05)
+        else:
+            logger.info('%s Connection established... (from %s)', self.LOG_PREFIX, self.client_address())
+            self.__clean_receive_buffer__()
+            self.__connection__.setblocking(False)
+            if self.__connect_callback__ is not None:
+                self.__connect_callback__()
+
+
+class tcp_client(tcp_base):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+    :param rx_log_lvl: The log level to log incomming RX-data
+    :type rx_log_lvl: int
+
+    This class supports a tcp-client transfering a serial stream of bytes (characters).
+
+    .. note:: You need a running :class:`tcp_server` listening at the given IP and port to communicate.
+
+    **Example:**
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_client.py
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_client.log
+    """
+    def __connect__(self):
+        if self.__socket__ is None:
+            # Create a TCP/IP socket
+            self.__socket__ = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            self.__socket__.setblocking(False)
+        # Connect the socket to the port where the server is listening
+        try:
+            self.__socket__.connect((self.host, self.port))
+        except socket.error as e:
+            if e.errno == 9:
+                self.__socket__.close()
+            elif e.errno != 115 and e.errno != 111 and e.errno != 114:
+                raise
+            else:
+                self.__connection__ = None
+                time.sleep(.05)
+        else:
+            logger.info('%s Connection to %s:%s established', self.LOG_PREFIX, self.host, self.port)
+            self.__clean_receive_buffer__()
+            self.__connection__ = self.__socket__
+            if self.__connect_callback__ is not None:
+                self.__connect_callback__()
+
+
+class tcp_base_stp(tcp_base):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+    :param rx_log_lvl: The log level to log incomming RX-data
+    :type rx_log_lvl: int
+
+    This is the base class for other classes in this module.
+
+    .. note:: This class is not designed for direct usage.
+    """
+
+    def __init__(self, host, port, rx_log_lvl=logging.INFO):
+        tcp_base.__init__(self, host, port, rx_log_lvl=rx_log_lvl)
+        self.__stp__ = stringtools.stp.stp()
+
+    def __clean_receive_buffer__(self):
+        logger.debug("%s Cleaning up receive-buffer", self.LOG_PREFIX)
+        self.__receive_buffer__ = []
+
+    def receive(self, timeout=1):
+        """
+        :param timeout: The timeout for receiving data (at least after the timeout the method returns data or None).
+        :type timeout: float
+        :return: The received data.
+        :rtype: str
+
+        This method returns one received messages via the initiated communication channel.
+        """
+        try:
+            return tcp_base.receive(self, timeout=timeout, num=1)[0]
+        except TypeError:
+            return None
+
+    def send(self, data, timeout=1, log_lvl=logging.INFO):
+        """
+        :param data: The message to be send over the communication channel.
+        :type data: str
+        :param timeout: The timeout for sending data (e.g. time to establish new connection).
+        :type timeout: float
+        :param rx_log_lvl: The log level to log outgoing TX-data
+        :type rx_log_lvl: int
+        :return: True if data had been sent, otherwise False.
+        :rtype: bool
+
+        This method sends one message via the initiated communication channel.
+        """
+        if tcp_base.send(self, stringtools.stp.build_frame(data), timeout=timeout, log_lvl=logging.DEBUG):
+            logger.log(log_lvl, '%s TX -> "%s"', self.LOG_PREFIX, stringtools.hexlify(data))
+            return True
+        else:
+            return False
+
+    def __receive_task__(self, queue_inst, rx_log_lvl):
+        if self.__connection__ is not None:
+            try:
+                data = self.__connection__.recv(self.RX_LENGTH)
+            except socket.error as e:
+                if e.errno == 104:
+                    self.__connection_lost__()
+                elif e.errno != 11:
+                    raise
+                else:
+                    time.sleep(.05)
+            else:
+                if len(data) > 0:
+                    logger.debug('%s -- <- "%s"', self.LOG_PREFIX, stringtools.hexlify(data))
+                    content = self.__stp__.process(data)
+                    for msg in content:
+                        logger.log(rx_log_lvl, '%s RX  <- "%s"', self.LOG_PREFIX, stringtools.hexlify(msg))
+                        self.__receive_buffer__.append(msg)
+                else:
+                    self.__connection_lost__()
+            self.__call_data_available_callback__()
+        else:
+            self.__connect__()
+        queue_inst.enqueue(5, self.__receive_task__, rx_log_lvl)
+
+
+class tcp_server_stp(tcp_server, tcp_base_stp):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+    :param rx_log_lvl: The log level to log incomming RX-data
+    :type rx_log_lvl: int
+
+    This class supports a tcp-server transfering a string. The string will be packed on send and unpacked on receive.
+    See :mod:`stp` for more information on packing and unpacking.
+
+    .. note:: You need a :class:`tcp_client_stp` to communicate with the server.
+
+    **Example:**
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server_stp.py
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server_stp.log
+    """
+    pass
+
+
+class tcp_client_stp(tcp_client, tcp_base_stp):
+    """
+    :param host: The host IP for the TCP socket functionality
+    :type host: str
+    :param port: The port for the TCP socket functionality
+    :type port: int
+
+    This class supports a tcp-server transfering a string. The string will be packed on send and unpacked on receive.
+    See :mod:`stp` for more information on packing and unpacking.
+
+    .. note:: You need a running :class:`tcp_server_stp` listening at the given IP and port to communicate.
+
+    **Example:**
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server_stp.py
+
+    .. literalinclude:: ../../tcp_socket/_examples_/tcp_socket__tcp_server_stp.log
+    """
+    pass