socketserver – фреймворк для сетевых серверов¶socketserver – A framework for network servers

Замечания по созданию серверов¶Server Creation Notes

В иерархии наследования пять классов, четыре из которых представляют синхронные серверы четырёх типов:

+------------+
| BaseServer |
+------------+
      |
      v
+-----------+        +------------------+
| TCPServer |------->| UnixStreamServer |
+-----------+        +------------------+
      |
      v
+-----------+        +--------------------+
| UDPServer |------->| UnixDatagramServer |
+-----------+        +--------------------+

Обратите внимание, что UnixDatagramServer наследует от UDPServer, а не от UnixStreamServer – единственное различие между IP- и Unix-стрим-сервером заключается в семействе адресов, которое просто повторяется в обоих Unix-классах серверов.

Версии с порождением процессов и потоками для каждого типа сервера можно создать с помощью миксин-классов ForkingMixIn и ThreadingMixIn. Например, класс потокового UDP-сервера создаётся следующим образом:

class ThreadingUDPServer(ThreadingMixIn, UDPServer): pass

Класс-примесь должен идти первым, так как он переопределяет метод, определённый в UDPServer. Настройка различных переменных-членов также изменяет поведение базового серверного механизма.

Чтобы реализовать службу, необходимо создать класс, производный от BaseRequestHandler, и переопределить его метод handle(). Затем можно запускать различные версии службы, комбинируя один из серверных классов с вашим классом обработчика запросов. Класс обработчика запросов должен быть разным для служб, работающих с дейтаграммами или потоками. Это можно скрыть, используя подклассы обработчиков StreamRequestHandler или DatagramRequestHandler.

Конечно, нужно подходить с умом. Например, нет смысла использовать сервер с порождением процессов (forking), если служба хранит состояние в памяти, которое может изменяться разными запросами, потому что изменения в дочернем процессе никогда не попадут в исходное состояние, хранящееся в родительском процессе и передаваемое каждому дочернему. В этом случае можно использовать потоковый сервер (threading), но, скорее всего, придётся использовать блокировки для защиты целостности общих данных.

С другой стороны, если создаётся HTTP-сервер, где все данные хранятся внешне (например, в файловой системе), синхронный класс фактически сделает службу «глухой» на время обработки одного запроса – что может занять очень много времени, если клиент медленно получает все запрошенные данные. Здесь подойдёт потоковый сервер или сервер с порождением процессов.

В некоторых случаях часть запроса можно обрабатывать синхронно, а завершать обработку в порождённом дочернем процессе в зависимости от данных запроса. Это можно реализовать с помощью синхронного сервера и явного вызова fork в методе класса обработчика запросов handle().

Другой подход к обработке нескольких одновременных запросов в среде, не поддерживающей ни потоки, ни fork() (или где они слишком дороги или неприемлемы для данного сервиса), заключается в ведении явной таблицы частично завершённых запросов и использовании select() для определения, какой запрос обрабатывать следующим (или следует ли обрабатывать новый входящий запрос). Это особенно важно для потоковых сервисов, где каждый клиент может быть подключен в течение длительного времени (если невозможно использовать потоки или подпроцессы). См. asyncore для другого способа управления этим.

Объекты сервера¶Server Objects

socketserver.fileno()¶

Возвращает целочисленный файловый дескриптор для сокета, на котором сервер прослушивает соединения. Эта функция чаще всего передаётся в select.select(), чтобы обеспечить мониторинг нескольких серверов в одном процессе.

socketserver.handle_request()¶

Обрабатывает один запрос. Эта функция последовательно вызывает следующие методы: get_request(), verify_request() и process_request(). Если предоставленный пользователем метод handle() класса-обработчика вызывает исключение, будет вызван метод handle_error() сервера. Если в течение self.timeout секунд не поступило ни одного запроса, будет вызван handle_timeout(), и handle_request() вернётся.

socketserver.serve_forever(poll_interval=0.5)¶

Обрабатывает запросы до тех пор, пока не поступит явный запрос shutdown(). Опрашивает на предмет завершения каждые poll_interval секунд.

socketserver.shutdown()¶

Сообщает циклу serve_forever() о необходимости остановиться и ожидает его завершения.

socketserver.address_family¶

Семейство протоколов, к которому принадлежит сокет сервера. Типичные примеры: socket.AF_INET и socket.AF_UNIX.

socketserver.RequestHandlerClass¶

Класс обработчика запросов, предоставленный пользователем; экземпляр этого класса создаётся для каждого запроса.

socketserver.server_address¶

Адрес, на котором сервер прослушивает соединения. Формат адресов зависит от семейства протоколов; подробнее см. документацию модуля socket. Для интернет-протоколов это кортеж, содержащий строку с адресом и целочисленный номер порта: ('127.0.0.1', 80), например.

socketserver.socket¶

Объект сокета, через который сервер будет принимать входящие запросы.

Классы серверов поддерживают следующие переменные класса:

socketserver.allow_reuse_address¶

Определяет, разрешает ли сервер повторное использование адреса. По умолчанию False, но может быть установлено в подклассах для изменения политики.

socketserver.request_queue_size¶

Размер очереди запросов. Если обработка одного запроса занимает много времени, все запросы, поступающие во время занятости сервера, помещаются в очередь – до request_queue_size запросов. Когда очередь заполнена, последующие запросы от клиентов получают ошибку «Connection denied». Обычно значение по умолчанию равно 5, но его можно переопределить в подклассах.

socketserver.socket_type¶

Тип сокета, используемого сервером; socket.SOCK_STREAM и socket.SOCK_DGRAM – два распространённых значения.

socketserver.timeout¶

Длительность тайм-аута в секундах или None, если тайм-аут не нужен. Если handle_request() не получает входящих запросов в течение тайм-аута, вызывается метод handle_timeout().

Существует несколько методов сервера, которые могут быть переопределены подклассами базовых классов сервера, например TCPServer; эти методы не предназначены для внешних пользователей объекта сервера.

socketserver.finish_request()¶

Фактически обрабатывает запрос, создавая экземпляр RequestHandlerClass и вызывая его метод handle().

socketserver.get_request()¶

Должен принять запрос из сокета и вернуть кортеж из двух элементов, содержащий новый объект сокета для взаимодействия с клиентом и адрес клиента.

socketserver.handle_error(request, client_address)¶

Эта функция вызывается, если метод handle() класса RequestHandlerClass вызывает исключение. По умолчанию она печатает трассировку в стандартный вывод и продолжает обработку следующих запросов.

socketserver.handle_timeout()¶

Эта функция вызывается, когда атрибут timeout установлен в значение, отличное от None, и по истечении тайм-аута не было получено ни одного запроса. В серверах с порождением процессов (forking) по умолчанию собирается статус завершившихся дочерних процессов, а в серверах с потоками этот метод ничего не делает.

socketserver.process_request(request, client_address)¶

Вызывает finish_request() для создания экземпляра RequestHandlerClass. При необходимости эта функция может создать новый процесс или поток для обработки запроса; классы ForkingMixIn и ThreadingMixIn делают это.

socketserver.server_activate()¶

Вызывается конструктором сервера для его активации. Поведение по умолчанию просто вызывает listen() для сокета сервера. Может быть переопределено.

socketserver.server_bind()¶

Вызывается конструктором сервера для привязки сокета к нужному адресу. Можно переопределить.

socketserver.verify_request(request, client_address)¶

Должна возвращать логическое значение; если значение равно True, запрос будет обработан, а если False, запрос будет отклонён. Эту функцию можно переопределить для реализации контроля доступа к серверу. Реализация по умолчанию всегда возвращает True.

Объекты RequestHandler¶RequestHandler Objects

Класс обработчика запросов должен определять новый метод handle() и может переопределять любой из следующих методов. Для каждого запроса создаётся новый экземпляр.

socketserver.finish()¶

Вызывается после метода handle() для выполнения необходимых действий по очистке. Реализация по умолчанию ничего не делает. Если setup() или handle() вызывают исключение, эта функция не будет вызвана.

socketserver.handle()¶

Эта функция должна выполнять всю работу по обслуживанию запроса. Реализация по умолчанию ничего не делает. Для неё доступны несколько атрибутов экземпляра: запрос доступен как self.request; адрес клиента как self.client_address; и экземпляр сервера как self.server, на случай, если потребуется доступ к информации, специфичной для сервера.

Тип self.request различается для датаграммных и потоковых служб. Для потоковых служб self.request – это объект сокета; для датаграммных – self.request представляет собой пару из строки и сокета. Однако это можно скрыть, используя подклассы обработчика запросов StreamRequestHandler или DatagramRequestHandler, которые переопределяют методы setup() и finish() и предоставляют атрибуты self.rfile и self.wfile. self.rfile и self.wfile можно читать или записывать соответственно для получения данных запроса или возврата данных клиенту.

socketserver.setup()¶

Вызывается перед методом handle() для выполнения необходимых действий по инициализации. Реализация по умолчанию ничего не делает.

Примеры¶Examples

import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The RequestHandler class for our server.

    It is instantiated once per connection to the server, and must
    override the handle() method to implement communication to the
    client.
    """

    def handle(self):
        # self.request is the TCP socket connected to the client
        self.data = self.request.recv(1024).strip()
        print("%s wrote:" % self.client_address[0])
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.send(self.data.upper())

if __name__ == "__main__":
    HOST, PORT = "localhost", 9999

    # Create the server, binding to localhost on port 9999
    server = socketserver.TCPServer((HOST, PORT), MyTCPHandler)

    # Activate the server; this will keep running until you
    # interrupt the program with Ctrl-C
    server.serve_forever()

class MyTCPHandler(socketserver.StreamRequestHandler):

    def handle(self):
        # self.rfile – это файлоподобный объект, созданный обработчиком;
        # теперь можно использовать, например, readline() вместо прямых вызовов recv()
        self.data = self.rfile.readline().strip()
        print("%s wrote:" % self.client_address[0])
        print(self.data)
        # Аналогично, self.wfile – это файлоподобный объект, используемый для записи ответа
        # клиенту
        self.wfile.write(self.data.upper())

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# Создать сокет (SOCK_STREAM означает TCP-сокет)
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

# Подключиться к серверу и отправить данные
sock.connect((HOST, PORT))
sock.send(bytes(data + "\n","utf8"))

# Получить данные от сервера и завершить работу
received = sock.recv(1024)
sock.close()

print("Sent:     %s" % data)
print("Received: %s" % received)

$ python TCPServer.py
127.0.0.1 wrote:
b'hello world with TCP'
127.0.0.1 wrote:
b'python is nice'

$ python TCPClient.py hello world with TCP
Sent:     hello world with TCP
Received: b'HELLO WORLD WITH TCP'
$ python TCPClient.py python is nice
Sent:     python is nice
Received: b'PYTHON IS NICE'

import socketserver

class MyUDPHandler(socketserver.BaseRequestHandler):
    """
    This class works similar to the TCP handler class, except that
    self.request consists of a pair of data and client socket, and since
    there is no connection the client address must be given explicitly
    when sending data back via sendto().
    """

    def handle(self):
        data = self.request[0].strip()
        socket = self.request[1]
        print("%s wrote:" % self.client_address[0])
        print(data)
        socket.sendto(data.upper(), self.client_address)

if __name__ == "__main__":
   HOST, PORT = "localhost", 9999
   server = socketserver.UDPServer((HOST, PORT), MyUDPHandler)
   server.serve_forever()

import socket
import sys

HOST, PORT = "localhost", 9999
data = " ".join(sys.argv[1:])

# SOCK_DGRAM – это тип сокета для UDP-сокетов
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# Как можно видеть, вызов connect() отсутствует; в UDP нет соединений.
# Вместо этого данные отправляются напрямую получателю через sendto().
sock.sendto(bytes(data + "\n","utf8"), (HOST, PORT))
received = sock.recv(1024)

print("Sent:     %s" % data)
print("Received: %s" % received)

import socket
import threading
import socketserver

class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):

    def handle(self):
        data = self.request.recv(1024)
        cur_thread = threading.current_thread()
        response = bytes("%s: %s" % (cur_thread.getName(), data),'ascii')
        self.request.send(response)

class ThreadedTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
    pass

def client(ip, port, message):
    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
    sock.connect((ip, port))
    sock.send(message)
    response = sock.recv(1024)
    print("Received: %s" % response)
    sock.close()

if __name__ == "__main__":
    # Port 0 means to select an arbitrary unused port
    HOST, PORT = "localhost", 0

    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
    ip, port = server.server_address

    # Start a thread with the server -- that thread will then start one
    # more thread for each request
    server_thread = threading.Thread(target=server.serve_forever)
    # Exit the server thread when the main thread terminates
    server_thread.setDaemon(True)
    server_thread.start()
    print("Server loop running in thread:", server_thread.getName())

    client(ip, port, b"Hello World 1")
    client(ip, port, b"Hello World 2")
    client(ip, port, b"Hello World 3")

    server.shutdown()

$ python ThreadedTCPServer.py
Server loop running in thread: Thread-1
Received: b"Thread-2: b'Hello World 1'"
Received: b"Thread-3: b'Hello World 2'"
Received: b"Thread-4: b'Hello World 3'"