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

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

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

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

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

class socketserver.ForkingMixIn

class socketserver.ThreadingMixIn

С помощью этих классов-миксинов можно создавать версии каждого типа сервера, использующие разветвление процессов или потоки. Например, ThreadingUDPServer создаётся следующим образом:

class ThreadingUDPServer(ThreadingMixIn, UDPServer):
    pass

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

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

block_on_close

ForkingMixIn.server_close ожидает завершения всех дочерних процессов, если только атрибут block_on_close не равен False.

ThreadingMixIn.server_close ожидает завершения всех недемонических потоков, если только атрибут block_on_close не равен False.

max_children

Задаёт, сколько дочерних процессов одновременно будет обрабатывать запросы для ForkingMixIn. При достижении лимита новые запросы будут ожидать завершения одного из дочерних процессов.

daemon_threads

Для ThreadingMixIn используйте демонические потоки, установив ThreadingMixIn.daemon_threads в True, чтобы не дожидаться завершения потоков.

Изменено в версии 3.7: ForkingMixIn.server_close и ThreadingMixIn.server_close теперь ожидает завершения всех дочерних процессов и недемонических потоков. Добавлен новый атрибут класса ForkingMixIn.block_on_close, позволяющий включить поведение, действовавшее до версии 3.7.

class socketserver.ForkingTCPServer

class socketserver.ForkingUDPServer

class socketserver.ThreadingTCPServer

class socketserver.ThreadingUDPServer

class socketserver.ForkingUnixStreamServer

class socketserver.ForkingUnixDatagramServer

class socketserver.ThreadingUnixStreamServer

class socketserver.ThreadingUnixDatagramServer

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

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

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

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

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

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

Объекты серверов

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: В метод serve_forever добавлен вызов service_actions.

service_actions()

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

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

shutdown()

Указывает циклу serve_forever() остановиться и ожидает его остановки. shutdown() необходимо вызывать, пока serve_forever() выполняется в другом потоке, иначе возникнет взаимная блокировка.

server_close()

Очищает ресурсы сервера. Метод можно переопределить.

address_family

Семейство протоколов, к которому относится сокет сервера. Часто используются, например, socket.AF_INET, socket.AF_INET6 и socket.AF_UNIX. Чтобы создать классы серверов IPv6, унаследуйте классы серверов TCP или UDP из этого модуля и установите атрибут класса address_family = AF_INET6.

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()

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

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().

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

class socketserver.BaseRequestHandler

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

setup()

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

handle()

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

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

finish()

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

request

Новый объект socket.socket, используемый для обмена данными с клиентом.

client_address

Адрес клиента, возвращаемый методом BaseServer.get_request().

server

Объект BaseServer, используемый для обработки запроса.

class socketserver.StreamRequestHandler

class socketserver.DatagramRequestHandler

Эти подклассы BaseRequestHandler переопределяют методы setup() и finish(), а также предоставляют атрибуты rfile и wfile.

rfile

Файловый объект, из которого считывается запрос. Поддерживает интерфейс чтения io.BufferedIOBase.

wfile

Файловый объект, в который записывается ответ. Поддерживает интерфейс записи io.BufferedIOBase

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

Примеры

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
        pieces = [b'']
        total = 0
        while b'\n' not in pieces[-1] and total < 10_000:
            pieces.append(self.request.recv(2000))
            total += len(pieces[-1])
        self.data = b''.join(pieces)
        print(f"Received from {self.client_address[0]}:")
        print(self.data.decode("utf-8"))
        # just send back the same data, but upper-cased
        self.request.sendall(self.data.upper())
        # after we return, the socket will be closed.

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.
        # We limit ourselves to 10000 bytes to avoid abuse by the sender.
        self.data = self.rfile.readline(10000).rstrip()
        print(f"{self.client_address[0]} wrote:")
        print(self.data.decode("utf-8"))
        # Likewise, self.wfile is a file-like object used to write back
        # to the client
        self.wfile.write(self.data.upper())

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, "utf-8"))
    sock.sendall(b"\n")

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

print("Sent:    ", data)
print("Received:", 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

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(f"{self.client_address[0]} wrote:")
        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:    ", data)
print("Received:", received)

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