socketserver — Фреймворк для сетевых серверов

Исходный код: Lib/socketserver.py

Модуль socketserver упрощает задачу написания сетевых серверов.

Существует четыре основных конкретных класса серверов:

class socketserver.TCPServer(server_address, RequestHandlerClass, bind_and_activate=True)

Он использует интернет-протокол TCP, который обеспечивает непрерывные потоки данных между клиентом и сервером. Если bind_and_activate имеет значение true, конструктор автоматически пытается вызвать server_bind() и server_activate(). Другие параметры передаются базовому классу BaseServer.

class socketserver.UDPServer(server_address, RequestHandlerClass, bind_and_activate=True)

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

class socketserver.UnixStreamServer(server_address, RequestHandlerClass, bind_and_activate=True)

class socketserver.UnixDatagramServer(server_address, RequestHandlerClass, bind_and_activate=True)

Эти менее часто используемые классы похожи на классы TCP и UDP, но используют сокеты Unix-домена; они недоступны на платформах, не являющихся Unix. Параметры такие же, как у TCPServer.

Эти четыре класса обрабатывают запросы синхронно; каждый запрос должен быть завершен до начала обработки следующего запроса. Это не подходит, если обработка каждого запроса занимает много времени, требует больших вычислений или возвращает много данных, которые клиент медленно обрабатывает. Решением является создание отдельного процесса или потока для обработки каждого запроса; для поддержки асинхронного поведения можно использовать классы-микшины ForkingMixIn и ThreadingMixIn.

Создание сервера требует нескольких шагов. Во-первых, вы должны создать класс обработчика запросов, унаследовав его от класса BaseRequestHandler и переопределив его метод handle(); этот метод будет обрабатывать входящие запросы. Во-вторых, вы должны создать экземпляр одного из классов серверов, передав ему адрес сервера и класс обработчика запросов. Рекомендуется использовать сервер в операторе with. Затем вызовите метод handle_request() или serve_forever() объекта сервера для обработки одного или нескольких запросов. Наконец, вызовите server_close() для закрытия сокета (если вы не использовали оператор with).

При наследовании от ThreadingMixIn для поточно-ориентированного поведения соединений, вы должны явно указать, как вы хотите, чтобы ваши потоки вели себя при внезапном завершении. Класс ThreadingMixIn определяет атрибут daemon_threads, который указывает, должен ли сервер ожидать завершения потоков. Вы должны явно установить этот флаг, если хотите, чтобы потоки вели себя автономно; значение по умолчанию False, что означает, что Python не завершит работу до тех пор, пока все потоки, созданные классом ThreadingMixIn, не завершат свою работу.

Классы серверов имеют одинаковые внешние методы и атрибуты, независимо от используемого сетевого протокола.

21.21.1. Примечания по созданию сервера

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

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

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

class socketserver.ForkingMixIn

class socketserver.ThreadingMixIn

Версии серверов с поддержкой форкинга и потоков можно создать, используя эти классы-микшины. Например, ThreadingUDPServer создаётся следующим образом:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

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

ForkingMixIn и перечисленные ниже классы с форкингом доступны только на платформах POSIX, которые поддерживают fork().

class socketserver.ForkingTCPServer

class socketserver.ForkingUDPServer

class socketserver.ThreadingTCPServer

class socketserver.ThreadingUDPServer

Эти классы предварительно определены с использованием классов-микшин.

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

Конечно, вам всё равно нужно использовать голову! Например, нет смысла использовать сервер форкинга, если сервис содержит состояние в памяти, которое может изменяться различными запросами, поскольку изменения в дочернем процессе никогда не достигнут начального состояния, хранимого в родительском процессе и переданного каждому дочернему.

В этом случае можно использовать сервер с потоками, но, вероятно, придётся использовать блокировки для защиты целостности общих данных.

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

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

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

21.21.2. Объекты сервера

class socketserver.BaseServer(server_address, RequestHandlerClass)

Это суперкласс всех объектов Server в модуле. Он определяет интерфейс, указанный ниже, но не реализует большинство методов, что делается в подклассах. Два параметра хранятся в соответствующих атрибутах server_address и RequestHandlerClass.

fileno()

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

handle_request()

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

serve_forever(poll_interval=0.5)

Обрабатывает запросы до явного запроса shutdown(). Проверяет запрос на закрытие каждые poll_interval секунд. Игнорирует атрибут timeout. Также вызывает service_actions(), который может использоваться подклассом или миксином для предоставления действий, специфичных для данного сервиса. Например, класс ForkingMixIn использует service_actions() для очистки процессов-сирот.

Изменено в версии 3.3: Добавлен вызов service_actions в метод serve_forever.

service_actions()

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

Добавлен в версии 3.3.

shutdown()

Указывает циклу serve_forever() остановиться и ожидать его завершения.

server_close()

Очистка сервера. Может быть переопределён.

address_family

Семейство протоколов, к которому принадлежит сокет сервера. Общие примеры — socket.AF_INET и socket.AF_UNIX.

RequestHandlerClass

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

server_address

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

socket

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

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

allow_reuse_address

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

request_queue_size

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

socket_type

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

timeout

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

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

finish_request(request, client_address)

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

get_request()

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

handle_error(request, client_address)

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

Изменено в версии 3.6: Теперь вызывается только для исключений, производных от класса Exception.

handle_timeout()

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

process_request(request, client_address)

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

server_activate()

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

server_bind()

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

verify_request(request, client_address)

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

Изменено в версии 3.6: Добавлена поддержка протокола менеджера контекста. Выход из менеджера контекста эквивалентен вызову server_close().

21.21.3. Объекты обработчика запросов

class socketserver.BaseRequestHandler

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

setup()

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

handle()

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

Тип self.request отличается для датаграммных или потоковых служб. Для потоковых служб self.request является объектом сокета; для датаграммных служб self.request является парой строки и сокета.

finish()

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

class socketserver.StreamRequestHandler

class socketserver.DatagramRequestHandler

Эти подклассы BaseRequestHandler переопределяют методы setup() и finish() и предоставляют атрибуты self.rfile и self.wfile. Атрибуты self.rfile и self.wfile можно соответственно читать и записывать для получения данных запроса или возврата данных клиенту.

Атрибуты rfile обоих классов поддерживают читаемый интерфейс io.BufferedIOBase, и DatagramRequestHandler.wfile поддерживает записываемый интерфейс io.BufferedIOBase.

Изменено в версии 3.6: StreamRequestHandler.wfile также поддерживает записываемый интерфейс io.BufferedIOBase.

21.21.4. Примеры

21.21.4.1. socketserver.TCPServer Пример

Это серверная сторона:

import socketserver

class MyTCPHandler(socketserver.BaseRequestHandler):
    """
    The request handler 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("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())

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

    # Create the server, binding to localhost on port 9999
    with socketserver.TCPServer((HOST, PORT), MyTCPHandler) as server:
        # 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 is a file-like object created by the handler;
        # we can now use e.g. readline() instead of raw recv() calls
        self.data = self.rfile.readline().strip()
        print("{} wrote:".format(self.client_address[0]))
        print(self.data)
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())

Разница в том, что вызов readline() во втором обработчике вызовет recv() многократно, пока не встретится символ новой строки, тогда как одиночный вызов recv() в первом обработчике просто вернёт то, что было отправлено клиентом в одном вызове sendall().

Это клиентская сторона:

import socket
import sys

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

# Create a socket (SOCK_STREAM means a TCP socket)
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
    # Connect to server and send data
    sock.connect((HOST, PORT))
    sock.sendall(bytes(data + "\n", "utf-8"))

    # Receive data from the server and shut down
    received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(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: HELLO WORLD WITH TCP
$ python TCPClient.py python is nice
Sent:     python is nice
Received: PYTHON IS NICE

21.21.4.2. socketserver.UDPServer Пример

Это серверная сторона:

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("{} wrote:".format(self.client_address[0]))
        print(data)
        socket.sendto(data.upper(), self.client_address)

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

Это клиентская сторона:

import socket
import sys

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

# SOCK_DGRAM is the socket type to use for UDP sockets
sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

# As you can see, there is no connect() call; UDP has no connections.
# Instead, data is directly sent to the recipient via sendto().
sock.sendto(bytes(data + "\n", "utf-8"), (HOST, PORT))
received = str(sock.recv(1024), "utf-8")

print("Sent:     {}".format(data))
print("Received: {}".format(received))

Вывод примера должен быть точно таким же, как для примера TCP-сервера.

21.21.4.3. Асинхронные миксины

Для создания асинхронных обработчиков используйте классы ThreadingMixIn и ForkingMixIn.

Пример для класса ThreadingMixIn:

import socket
import threading
import socketserver

class ThreadedTCPRequestHandler(socketserver.BaseRequestHandler):

    def handle(self):
        data = str(self.request.recv(1024), 'ascii')
        cur_thread = threading.current_thread()
        response = bytes("{}: {}".format(cur_thread.name, data), 'ascii')
        self.request.sendall(response)

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

def client(ip, port, message):
    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
        sock.connect((ip, port))
        sock.sendall(bytes(message, 'ascii'))
        response = str(sock.recv(1024), 'ascii')
        print("Received: {}".format(response))

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

    server = ThreadedTCPServer((HOST, PORT), ThreadedTCPRequestHandler)
    with server:
        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.daemon = True
        server_thread.start()
        print("Server loop running in thread:", server_thread.name)

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

        server.shutdown()

Вывод примера должен выглядеть примерно так:

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

Класс ForkingMixIn используется аналогичным образом, за исключением того, что сервер запустит новый процесс для каждого запроса. Доступен только на платформах POSIX, которые поддерживают fork().